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I ntroduction 



With the creation of the partially independent CodeGear business unit within 
Borl and and the su bsequent sal e of the busi ness un i t to E mbarcadero Tech no- 
logies, Delphi has seen a significant increase in i nvestment and isonce again a 
growing and vibrant product thanks to its new technical features and to a 
developer community gaining in morale and affection, after a few years of slow 
growth and terms of capabilities and dwindling passion. 

Embarcadero is investing morein Delphi than Borland did over almost the 
enti re I ife of the product, and also i mprovi ng the way it reaches out to the com- 
munity. Long considered a "cash cow" with littlefuture ahead of it, the product 
is now clearly at the center of Embarcadero's developer tools strategy, focused 
on native cross- platform development (which isgoingto be the direction of 
future versions of Del phi , accordi ng to the current product road map 1 ) . 

Delphi 2010 isanother very significant step in this direction, after the impress- 
ive Delphi 2009 and a rather good Delphi 2007 release. From increased RTTI 
support to a significantly improved I DE; from the opening up to new databases 
(like Firebird) to the support of growing standards (like REST), Delphi 2010 is 
much more than an incremental new version. Its extended support for the 
Win32 platform, makes the latest Delphi the best tool, by far. for native devel- 



1 The most recent Del ph i road map, at the ti me of th i s wri ti ng, can be f ou nd at: 
http:// edn.embarcadero.com/article/39934 
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opmentfor Windows 7. By devoting more than a couple of hundred pages to 
the new features of the product, this book is a testi mony to the significant 
extension this version of Delphi offers to developers. 



My Delphi Handbook Series 

After a long series of M astering Delphi books (published first through Sybex 
and then Wiley, when it acquired Sybex), over the last few years I've focused on 
specific books devoted to new features of individual versions of the product. 
The Del phi Handbook series doesn't cover Delphi from the ground up, but 
focuses only on new features. 

By the time you are reading this, it should be possible to buy "reprints" of some 
of my classic Delphi books, along with buying my Mastering Delphi 7or2005 
from online and traditional resellers. My basic offering is Essential Pascal 2 . 

Delphi 2007 Handbook, the first of my self-published volumes, covered 
new features from Delphi 7 to Delphi 2007, from I DE updates to language 
extensions, focusi ng on Wi ndows Vista support and on the dbExpress data 
access library. This is the list of the chapters: 

. The Del phi 2007 IDE 

• Code Tempi ates and Ref actori ng 

• Project Management and MSBui Id 

• The Debugger 

• Recent U pdates to the Del phi Language 

• Core RTL Changes 

• Changes in the VCL 

• Memory Management (and Robust Applications) 

• Windows Vista and the VCL 

• Database Support and dbExpress 4 

• I nstal lAware and Other Tools 

• Upgrading Projects to Delphi 2007 



2 Essential Pascal isan introduction to the core features of the Pascal language. The focus 
is on traditional language structures and does not include object-oriented programming. 
M ore i nformati on at the book page: http:// www.marcocantu.com/ epascal 
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The Delphi 2009 Handbook had a long section on Unicode and delved into 
the significant changes to the language, which included generics and anonym- 
ous methods. There were also sections on the Ri bbon user i nterface and the 
new DataSnap multi-tier architecture. This isthe chapters list: 

• What is Unicode? 

• The Unicode String Type 

• Porting to Unicode 

• New I DE Features 

• Generics 

• Anonymous M ethods 

• M ore Language and RTL Changes 

• VCL I mprovements 

. COM Support in Delphi 2009 

• The Ribbon 

• Datasets and dbExpress 
. DataSnap 2009 

The past two Delphi Handbooks are on sale in printed form both on Lulu and 

Amazon, while electronic versions can be bought online. Follow links on the 

book pages for buying printed or electronic versions: 

h 1 1 p : / / www. marcocantu. com/dh2007 
h 1 1 p : / / www. marcocantu. com/dh2009 



The Delphi 2010 Handbook 

The current book continues with this tradition by focusing on new features of 
Delphi 2010. Therefore, if you are upgrading from an older version of the 
product, you might want to read one or both previous handbooks fi rst 3 . 

There isn't a specific focus in this book, as there isn't one in Delphi 2010. The 
release brings to completion some of the recent features, likeimproved support 
for the Win32 API (with specific focus on Windows 7) and the new DataSnap 
architecture originally introduced in Delphi 2009 (now with HTTP support). 



3 I might create a single all -encompassing Handbook Collection, but this sti 1 1 notafirm 
plan and it might not happen. 

Marco Cantu, Delphi 2010 Handbook 



8 - Introduction 



One of the new foundations of the product is its extended RTTI support and the 
i ncl usion of attri butes i n the Object Pascal language, the subject of one of the 
longest chapters. There was also a significant facelift in the I DE and debugger, 
with some easy to use features, and other more complex to understand and 
configurelDE extensions using the Del phi OpenToolsAPI. 

N eedl ess to say the book covers al I of thi s, and some more. H ere i s the I i st of 
the chapters, with more details available in the table of contents: 

. 1 A Better I DE 

• 2. The Debugger 

• 3. Extended RTTI and Attributes 

• 4. M ore and the Compi I er and the RTL 
. 5. The VCL and Wi ndows 7 

• 6. Touch and Gestures 

• 7. Database Access and DataSnap 
. 8. REST Web Services 

The specific web page devoted to this book, including updates, source code 
downloads, and other information is at: 

h 1 1 p : / / www. marcocantu. com/dh2010 



Editor and Tech Reviewers 

This book as seen the contribution of an editor and several tech reviewers, 
involved at various degrees, which provided a huge help and I won't beableto 
thank enough. The editor of this book (as of all my latest Delphi books) was 
Peter Wood, an IT professional who lives in Malaysia. I got technical feedback 
from Holger Flick, Marco Breveglieri, Stefan Van As, DanieleTeti, and Chris 
Bensen. H ere is a short profi le of each of them. 

Daniele Teti 

Daniele (http://www.danieleteti.it) is the R&D Director of bitTi me Software, 
the I tal i an representati ve of E mbarcadero. H e i s a passi onate software 
developer and has been a speaker for Italian conferences on Delphi, PHP, 
design pattern, and multi-tier applications. Daniel eh as started a few open 
source project NketheDataSnapFilterCompendium, a STOMP client, and a 
dependency injection framework for Delphi. 
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Marco Breveglieri 

Marco (http://www.marco.bre/eglieri.name) in a long time Del phi program- 
mer, trainer, and consultant, primarily involved in Microsoft Windows based 
software, targeti ng both the nati ve and the . N ET F ramework pi atforms, and 
Web development using (X)HTM L, CSS, J avaScript frameworks, and M icrosoft 
ASP.NET MVC. 

Chris Bensen 

Chris (http://chrisbensen.blogspot.com) is a member of the Delphi R&D team 
who helped reviewing the chapter on touch and gestures, one of the areas of the 
product he worked on. He's also a great photographer. 

Holger Flick 

Holger (http://www.flickdotnet.de/) is a Delphi top developer and conference 
speaker, and it part of German's Delphi Expert team. Holger worked on Q&A 
for Embarcadero and has a deep knowledge of the product. 

Stefan Van As 

Stefan (http://www.dutchdelphidude.com) is a "Dutch Delphi Dude" and the 
current author of TopStyle4, a great HTML and CSS editing tool written in 
Delphi. 



Author 

I'm Marco Cantu, the author of this book. I've been inthe "Delphi book writing" 
busi ness ever si nee the f i rst versi on of the product, when I rel eased the ori gi nal 
"Mastering Delphi" (a hefty tome of 1,500 pages). That was not my first writing 
experience, as I had previously written works on Borland C++ and the Object 
Windows Library. 

TheMastering Delphi series, published bySybex, was one of the best- selling 
Delphi book series for several years, with translations into many languages and 
sold in bookshops all over the world. More recently I started self-publishing the 
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Delphi Handbook series, availablefrom multiple print-on-demand outlets, 
including Lulu and Amazon, and in PDF format. 

Beside writing, I keep myself busy with consulting (mostly on applications 
architectures), help selling Delphi in Italy, do code reviews, Delphi mentoring, 
and general consulti ng for developers. I 'm a frequent speaker at Del phi and 
general developer conferences (in Europe and in the Unites States), including 
the recent online CodeRage conferences organized by Embarcadero. 

In 2009, CaryJ ensen and I gave public training in both US and Europe at the 
jointly organized Delphi Developer Days, which areal ready planned for May 
2010; for details (and future dates) see: 

8 h 1 1 p : / / www. del phi devel operdays. com 

I f you are i nterested i n i nviti ng me to speak at a publ ic event or give a trai ni ng 
session (on new Delphi features or any advanced Delphi subject) at your com- 
pany location, feel free to send me a note by emai I . 



Contact I nformation 

Tofollow my activity you can use several online resources and communities. 

I n the following list you can see my blog (which I tend to keep quite active), my 
not-so-up-do-date personal site (a summary of my activities), my company site 
(with training offers), my Twitter account, and my Facebook page: 



htt p 
htt p 
htt p 
htt p 
htt p 



//blog, ma rcocantu.com 

/ / www. marcocantu. com 

/ / www. wl ntech-ltalla.com 

/ / 1 wl 1 1 e r . com/ marcocantu 

//www. facebook. com/marcocantu 



I have an online mailing list based at Google groups. I also run an online news- 
group with a section devoted to discuss my books and thei r content. Here are 
the respective URLs: 

http: / / groups, googl e. com/ group / marco_cantu 

http: / /del phi . newswhat. com/foruml I stgroups?are a =ma r c oc a n t u 

Finally, feel free to drop mean email at my public address, although I generally 
don't offer tech support vi a emai I : 

marco.cantu@gmai I .com 
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Chapter 1: A 
Better I DE 

The I integrated Development Environment (or I DE) is, for most developers, the 
key tool for writing applications with Delphi. ThelDE in the2010 version gota 
significant face lift, aimed at improving its overall usability. Rather than sport- 
ing incredible new features, the Delphi I DE lets developers perform many 
common tasks more easi ly and more quickly. 

This chapter covers the mai n i improvements of the I DE, without getti ng i nto too 
much detail, as in most cases it will be rather easy to pick them up. Still, there 
are I ess visible features and details you might easily miss which I'll try to cover. 



I installation 

As is true of the last few versions, the installation of 2010 Delphi is based on 
InstallAware. Installing the product is generally quite a smooth process, but 
there are a few elements worth menti oni ng. 
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The first relates to the requirements for the machines on which Delphi 2010 is 
being installed. As the I DE itself uses some .NET features, the presence of .NET 
3.5 SP1 4 has been added to the prerequisites. If you keep your Windows 
machine updated, you're likely to have already installed it. 

Another change in the requirements is that Windows 2000 is no longer suppor- 
ted as a development platform, although it isstill fully supported asatarget 
operating system for running applications compiled in Delphi 2010. Support 
for running appl i cations on Windows 9x was already dropped in Delphi 2009. 

It is not that you absolutely cannot run the Delphi IDE on Windows 2000, but 
that Embarcadero Technologies gives you no guarantee it will work. In case you 
want to try to install Delphi 2010 on this operating system you can run the 
installation program with a specific flag 5 : 

| Set up. exe / wi n 2 k 

On a very positive note, even if this is really a minor issue, in the Delphi 2010 
installer you can paste all four sections of the serial number at once, rather than 
having to paste each individual section. 

Finally, consider that you can significantly reduce the installation footprint of 
the help system (and make the information much more appropriate to Delphi) 
if you disable the installation of the Microsoft Platform SDK, when installing 
the Delphi help. Thedetailsarein this blog post by DeeElling: 

| ht t p: / / bl ogs, embar cader o. com/ dee el I i ng/ 2 0 0 9 / 12/ 0 7 / 3 8 3 1 0 

Proxy Configuration 

As an aside, there are two options for installing Delphi 2010 (and Embarcadero 
RAD Studio 2010). One is to buy or download the DVD with the complete ver- 
sion of the software. The second is to get the small footprint installer (the one 



4 You might not be aware but .NET 3.5 SP1 provides countless improvements and is basic- 
ally a brand new version of .NET compared to .NET 3.5. It has new libraries and features, 
not only bug fixes or limited changes. The reasons it was delivered as a patch were mostly 
commercial: to deliver it as an update and let more people download and install it on 
their machines, compared to a new version you must specifically decide to install. 

5 Thewin2kinstallationflagdisablesthecheckforWindows2000 done by the installer, it 
doesn't change anything in the installation to make Delphi work on that version of the 
operating system. You can use it, but you won't be able to access technical support if any- 
thi ng goes wrong. 
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you'll generally receive when buying the Electronic Software Deli very (ESD) 
version of Delphi. Thissmaller installer will retrieve only the required installa- 
tion files automatically based on your configuration and the edition you 
licensed. 

There have been several reports about problems with this i nstal ler i n the past, 
for developers behind a firewall and with a proxy configuration. What is not 
mentioned well enough is that the installer uses port 80 for downloading the 
installation files and that it uses the system wide proxy defined in the I nternet 
Explorer configuration. So you shouldn't have any problems installing the ESD 
version even via a proxy server, providing you have I nternet Explorer properly 
configured. 



I installation Folders 

For a long time Del phi was installed under the Program Files\ Borland folder. 
With changes in the product ownership (first the Borland's CodeGear division 
and later Embarcadero Technologies) and the need to support Windows Vista 
fol der per mi ssi ons, the overal I structu re has kept changi ng consi derabl y. 

The main installation folder is now (by default): 

C:\Program F i I e s \ E mba r c a d e r o\ RAD Studi o\7. 0 

Other relevant folders include(on my computer, using the defaults) respect- 
ively projects, examples, database configuration, and sample database data: 

C:\Users\Marco\Documents\RAD Studi o\Proj ects\ 
C: \ Us e r s \ P u b I i c\ Doc ument s\ RAD Studi o\7. 0 
C:\Users\Publ i c\ Doc ument s\ RAD S t ud i o\ d b E x p r e s s \ 7 , 0 
C:\Program Files\Common F i I e s \ Co de Ge a r Shared 

These folders are not very much different from the past two versions of the 
I DE, with the welcome addition of a sub-folder for thedbExpress configura- 
tion. 

While the main installation folder has been changed from CodeGear to Embar- 
cadero, the Registry settings are still saved under the more familiar: 

| HKE Y_ CURRENT, USE R\ Soft war e\ CodeGear \BDS\ 7, 0 
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First I mpressions 

When you first start Delphi 2010, you won't see lots 
of big differences from Delphi 2009, but cleaner 
graphics, with new icons for thelDE and for your applications, by default. The 
new icon and style borrows heavi ly from the company style, but also revamps 
some of the classic elements of Delphi, I ike the three-column templeand the 
Greek helmet (shown up here). Needless to say you might likethe new style or 
not, as it is mostly a matter of taste. I think it is a good step in the right direc- 
tion, a more modern look without betraying the product history. 

The overal I user i nterface has been cleaned up somewhat, replaci ng some of the 
older dialog boxes of the product with versions that have a more modern user 
interface and (in many cases) extended search options. As an example, con- 
sider the View Form dialog box, now properly renamed Search for forms: 



Q Search for formi 



0.(6 



g Fwm39 (SimpleTeslMaffTFofm.pds} 
3 Form** (UniHO.pas) 



V;AI ffies in project group 



Cancel 



9 Viiw Form 


iill&i} OK 


■FcraM 


Cancei 




1 1 




J . All files in project group 




GV ARAD Stud i o'vPf oj t ct s\we*ver\ SetC astM a i mForm>pas 



Not only does it have a nicer look, compared to the older one with the gray 
background, but it also has a very handy search capability, terribly useful for 
large projects. The View Units dialog box had been given the same kind of 
improvement. A similar makeover was made to the Use Units dialog box, 
covered at the end of this chapter. Oddly enough now that some of these dialog 
boxes have been cleaned up, most developers will use them less and less, 
simply because the information they list (I ike the forms and the units of the 
current project or the projects in the current project group) now shows up in 
the new I DE I nsight dialog box, a sort of central starting point to find just about 
anything you might want to look for in the I DE and the current project. 
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I DE I nsight 



IDE Insight 



mi 



Both newcomers and expert users can easily get lost in the large number of 
menu items, settings, components, and features you can activate in the I DE. At 
ti mes even experts get lost because features were moved from a versi on of 
Delphi they spent a lot of time with. That's whythe team grabbed an idea that 
other development tools already implement and came up with searching capab- 
ilities in several dialog boxes 
(more on these later) and with 
an overall search mechanism 
for the entire IDE, called "IDE 
Insight". 

You activate this window by 
pressi ng the F6 key (or by 
using Ctrl +<period>) 6 . You 
can seethe IDE I nsight dialog 
box here on the ri ght. 

As you start typing into this 
dialog box, it will show a 
f i Itered I i st of j ust about any- 
thing you might want to look 
for in the IDE: 

• Commands of the main menu of thelDE, i ncluding those added dynamic- 
ally in theTools menu or by Wizards or extensions of any kind (but the 
menu items of local popup menus) 

• Component Palette elements, where the current view is a visual designer, 
li ke a form or a data module. 

• Components used by the current designer, again where the current view is 
a visual designer. Components depend on the installed packages, and obvi- 
ousl y i ncl ude thi rd- party ones. 

• Code Templates, where the current view is an Object Pascal source code 
editor, aC++Builder editor, or any other editor supporting code templates. 



Qrl 


Commands 






Desktop SpeedSettings 






Files 






Forms 






New Items 






Open Files 






Preferences 






Project Options 






Projects 






Recent Files 








Show all 


OK 


Cancel 





6 You might have to press Alt- Fl if you are not using the default key bindings. 
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. Desktop Speed Setting, usually managed with the corresponding tool bar 
of the mai n form, the one with the smal I combo box. 

• Files include the list of files of the current project (and other projects in the 
group) and isavailableonly if a project is active in the Project Manager. 

• Forms filters the forms and designers of the current project, again only if a 
project is active. 

• New I terns has el ements of the N ew I terns di alog box. 

• Open Files provides fast access to any file currently open in the editor. 

• Preferences filters on theindividual elements of the IDE preferences (the 
Tools | Options dialog box) and will open the corresponding page of thedia- 
log box when selected. 

• Project Options does the same with the options of the current project 
(again, you need to have a project open). Finding project options by typing 
thei r names is a superb feature I 'm using a lot. 

• Projects let's you jump to a project of the current project group. 

• Recent Files and Recent Projects filter the recently closed source code 
files and projects (which in Delphi 2010 can be customized much more than 
in the past, as we'll seein the section "Many More Recent Files"). 

Notice that as you start searching, the I DE I nsight dialog will show only a few 
elements of each category, unless you press the "Show all matches" button or 
the use correspondi ng Ctrl +E shortcut (which toggles between showi ng al I cat- 
egories with the best match i n each one or showi ng al I matches) . 



Filter Wild Cards 

What is less i ntuiti ve to figure out is that you can use wi Id cards when typi ng i n 
this search box (and most other search boxes avai lable i n the IDE): 

• ? wi 1 1 match any si ngle character 

• * wi 1 1 match zero, one, or more characters 

Notice that an implicit* is automatically added both at the beginning and at the 
end of the search text to match sub stri ngs. The same wi Id cards work i n most 
of the other fi Itered search di alog boxes added to the IDE. 
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Advanced: Customizing IDE Insight 

Warning: This is an advanced section using Del phi's Open Tools API . 
I f you are not i nterested i n extendi ng the Del phi IDE or have never 
used such a low-level API, you might want to skip this section. 

The list of elements in thelDE Insight is quite extensive, but there are certainly 
many others you might want to add to it. This is why the Delphi 2010 has a new 
OpenToolsAPI (the extensions you can register with the IDE) specifically 
intended for adding custom I DE I nsight entries. I n this and the next chapter, 
I'll becoveringacoupleof specific IDE extensions written using theOpen Tools 
API , but we have no room to discuss it from a broad perspective 7 . 

Here I'm going to show you a trivial example, which has no particular goal 
other than addi ng an entry to that wi ndow. There are certai nly several i nterest- 
i ng ways to extend I DE Insight, from presenting existing Delphi files and 
projects to open (after searching some folders) to integrating more sophistic- 
ated bookmarks, from code search on web sites to hooking up help pages. 

Although I don't have room for a detai led coverage of the architecture of 
Delphi's Open Tools API , here I 'm presenting a demo that can get you started 
in creating your own I DE I nsight extensions. 

The service i nterface you have to cal I to i nteract with this portion of the I DE is 
called I OTA I DEI n s i g h t Ser v i c e . One of its methods, A d d I t em, lets you add 
an element to the I DE Insight window. You can do this when registering the 
given unit of your design time package: 
va r 

f i r st I DEI ns i ght : I NTAI DE I n s i g h 1 1 t e m; 

procedure Regi st er ; 
begi n 

f i r st I DEI ns i ght : = Tl DEI n s i ghtTest. Create! 'First Test'); 
( Borl andl DEServi ces as I OTAI DEI nsi ghtServi ce) . Addl tem( 
fi rstl DEI nsi ght, ' Cant ool s ' ) ; 

end; 



7 I n the f i rst few years of Del phi , there was some extensi ve documentati on of the Open 
Tools API , which was originally way more limited than it is today. Now there are some 
on line references, often not really up-to-date. Even some commonly used I DE extensions 
stick to low-level techniques rather than using newer portions of this API . Even though a 
good part of the API methods are commented in theToolsApi unit, it is true that it is far 
from trivial to start using it. I have written papers on this topic in the past and presented 
it at conferences, but I 've not been ableto publish anything on the topic since Delphi 3! 
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The code first creates an object of the T I DEI nsi ghtTest class, which imple- 
ments the required I NT Al DEI nsi ghtl t em interface as you'll seeshortly; 
second, it adds that item to a new section of the I DE I nsight wi ndow (cal led 
'Cantools' after all of my I DE extensions). 

There is further code in the unit to remove the I DE I nsight item before the 

package is unloaded: 

procedure Removel DEI nsight; 
begl n 

( Borl andl DEServi ces as I OTAI DEI nsi ghtServi ce) . 

Removeltem (fi rstl DEI nsi ght) ; 
firstlDEInsight := nil; // it is an interface 
end; 

initialization 

f i nal i zat i on 

Removel DEI nsi ght; 

The core of the code is in the T I DEI nsi ghtTest class, which implements the 
I NTAI DEI nsi ghtl t em interface and the basic I OTANot i f i er i nterf ace. The 
class is defi ned as fol lows, with the methods grouped by i nterface: 
type 

Tl DEI ns i ght Test = class ( Tl nt erf acedObj ect , 

I NTAI DEI nsi ghtl tern, I OT ANo t i f i e r ) 
pr i vat e 

f F i I e N a me : string; 

f Description: string; 
publ i c 

constructor Create (const fName: string); 
{ I NTAI DEI nsi ghtl tern } 

function Dr awText ( Canvas : TCanvas; Rect: TRect; 

var DrawDefault: Boolean; DoDraw: Boolean = True): Integer; 
procedure Execute; 
function Ge t Des c r i p t i on : string; 
function GetDescri pti onSearchabi e: Boolean; 
function Ge t Gl y ph ( Bi t ma p : TBitmap): Boolean; 
function GetSti cky: Boolean; 
function Ge t Ti 1 1 e : string; 
function GetVisible: Boolean; 
procedure Update; 
{ I OTANot i f i er } 
procedure Af t er Save; 
procedure BeforeSave; 
procedure Destroyed; 
procedure Modified; 
end; 
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Most of the methods have a rather trivial implementation, with the constructor 
taking a string parameter that is later returned as the item title. The descrip- 
tion, i nstead changes every time the Upd at e method is called: 

constructor Tl DEI nsi ghtTest. Create(const aName: string); 
begi n 

f N a me : = a N a me ; 

fDescri pti on := 'Sample IDE Insight entry'; 
end; 

function Tl DE I n s i g h t Tes t . Ge t T i t I e : string; 
begi n 

Result :=fName; 
end; 

function Tl DE I n s i g h t Tes t . Ge t Des c r i p t i o n : string; 
begi n 

Res ul t : = f Desc r i pt i on; 
end; 

procedure Tl DEI nsi ghtTest. Update; 
begi n 

fDescri ption := 'Sample IDE Insight entry, last updated at: ' + 
Ti meToSt r ( Now) ; 

end; 

You can see the effect of these definitions in the image below, taken from the 
I DE I nsight pane after i nstall i ng the package with this custom extension: 



IDE Insight 






1 


Or fi| 








Can tools (1) 




First Test [Sample IDE Insight entry r last updated at: 5 : 12: 1 7 PM) 




Code Templates (2) 








►[2 try finally [tryf) 








Commands [9} 








File Browser 








Mew Items [3} 








f 3 ^ MSBuild Targets File 








■Bin if i i fill 










Show all 


tx || 


Cancel 


1 





, ' 



As a user selects the new item, the Execute method I DE I nsight object is 
called. In my case the implementation is not terribly interesting, but you can 
see the output along with the source code of its E x e c u t e method: 
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90 



procedure TIDElnsi ghtTest . Execute ; 
begin 

ShowMessage ('Got it: ' + f Name) ; 
end; 

function "T- TrcETnc-i nhfrTort — fifltnflgrn'nti nr ; String; 

begin Cujtomin;ighi - Embarcadero RAD SU«tio 2310 - Cujto- 

Result 
end; 



Got >c Fim Ttst 



function T 
begin 

Result := False; 
end; 



searchable : 



Again, this isonly an example showcasing the technology, not useful in itself. 
The ability to pi ug i n custom actions i n the I DE as you customize it beyond the 
planned activities (new components, new wizards, new Live Templates, new 
Tools configurations) is a significant change from the past. Let's hope open 
source communities and developers of Delphi paid add-on tool stake advantage 
of this feature. 



The Delphi 2010 Editor 

The Delphi 2010 editor sees limited changes, some of which are i nteresti ng in 
terms of usabi I ity. Let me start with the most si mple ones. 

Si nee the early days of Delphi, and of its Turbo Pascal predecessor, developers 
usi ng this language have got the habit of i ndenti ng thei r source code with two 
spaces rather than a tabulator, which is a more common approach in other lan- 
guages. That's why theTab key has been neglected for so much time, contrary 
to other development environments. 

Intheeditorof Delphi 2010, if a code block (of oneor more lines) is high- 
lighted theTab key will indent it, while pressing Shift +Tab will unindent it. 
This is exactly I ike using the Ctrl +Shift-H and Ctrl +Shift+U key combination 
that have been availablefor a longtime. As you can see the only reason for this 
change is to hel p developers coming from other development envi ronments or 
those who regularly have to use more than one. 

Another small but nice featureisthe ability to move editor bookmarks (which 
have been persistent between editing sessions since Delphi 2007) to different 
lines by draggi ng them in the gutter at the side of the editor. There is a specific 
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icon that gets displayed during this drag operation. As we'll see in the next 
chapter, a similar dragging operation is available also for breakpoi nts and 
(believe it or not) the instruction pointer. 

Among new options thereisthe ability to show all of the search matches (a new 
feature, discussed next) and to disable code folding (which was previously only 
avail able through a registry setting). 

As you search for a term, all search terms found in the current file will be high- 
lighted, using the color specified as "Additional search match highlight" 8 (worth 
mentioning becausel think you might really want to change the default, which 
I don't particularly like). 

The Search Pane 

In past versions of Delphi you could use the Ctrl +F combination (or the Search 
| Find menu command) to open a search dialog box, and afterward press F3 to 
search for the next occurrence of the term. A common alternative was to use 
the I ess powerful, but faster to use, Ctrl+E combination (invoking the Search | 
I ncremental Search command), and then start typing in the editor status bar 
and j ump to the searched el ement wh i I e typi ng. 

Both Find and I ncremental Search commands show specific search panes at 
the bottom of the editor, maki ng the former easier to use but keepi ng the dif- 
ference i n the behavior. When you cal I Fi nd you get the pane above but need to 
press Enter (or click on one of the arrow buttons) to activate the search; when 
you use I ncremental Search you search as you type but have fewer options: 

▼ 'v? ^ £ O Case sensitive O Whole words Regular expression Search selection 

I n both cases the number of matches is displayed and al I elements found that 
are vi si bl e i n the edi tor wi 1 1 be hi gh I i ghted . N oti ce al so that whi I e you can use 
the arrow keys to move from a match to the next one and back, the cl assi c F 3 
key and Shift + F3 keys sti 1 1 work. A related new feature is that as you get to the 
end of the fi le, Del phi wi 1 1 ask you to "Restart search from the begi nni ng of the 
file" and let you make the "wrap around" setting permanent. (You'd late be able 



8 I n the Editor options | Colors page of the Options dialog box, this color is the last entry in 
the Elements list. 
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to change this setting in the main page of the Editor Wrapped around r-j ^ 

1 match found ^ 

options.) In any case the wrap status is displayed at the 
right end of the pane, as shown here on the side. 



Searching with Directory Groups 



These i mproved file searching capabilities relate to finding information in the 
current file in the editor. For searching multiple files in the editor, in the cur- 
rent project, or in a given folder and its sub-folders, Delphi provides the Search 
| Find in Files command (or Ctrl+Shift+F). 

This dialog box was made more flexible in Delphi 2010 by adding support for 
searching in multiple folders and for user-defined Directory Groups, a set of 
folders the user can refer to 
using a name. The find in 
Folders pane of the Find in 
Fi les Di alog box looks I i ke on 
the side here. 



File mask: 



.pas 
Directories: 



C:\Users^arcQ\DQajment3^AD Studio^rojects;C: ^sers^ublk ^ | __)| 



I I Indude subdirectories 



I n the Di rectories combo box 
you can have one or more 

folders, while in older versions of Delphi you could enter only one folder name. 
There is also a second button, with a new relevant behavior: 



The first button on the right (the one with a single folder) lets you pick 
one folder as in the past 

The second button (the one with two folders), opens up a new Select 
Directories dialog, displayed below). 



(1^ Select Directories 



Directories to search 



c_ : tyJsers ^larco'pocuments V^AD Studio ip rojects 
C : ljusers "public documents ^p,AD Studio \7, 0 



You can now type the folder names, or pick afolder on each line with the 
upper button (with the folder), and cleanup invalid paths with the second 
button (the X over the page) . 
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The bottom portion of the dialog can be used to give a name to a group of 
folders, which can later be used among the directories to search by prefixing 
the name with the @ sign. If in doubt, you can add a group to the list in 
the upper half of the dialog using the up arrow button (hereon the right) 
that shows up as you select a group name i n the combo box: 



Select Directories 



Directories to search 



C:\UsersV^arcoV3ocunnentsty3.AD Studio projects 
^examples 



Directory groups 



Group name: examples 



Group contents.: 

CiUJsers'fublicpocijnnentsV^AD Studio\7.0 
C:\Users l j= l ublic l pocijments'^AD Studio\6.0 



OK 



Cancel 



- t te> X. 



Help 



The actual linelisted in the search dialog (which you can also type manually) 
would belike: 

C:\Users\Marco\Documents\RAD Stjdi o\Proj ects; @e x a mp I es 



The Code Formatter 

Many Delphi developers havelong relied on third- party source code formatters 
to clean up the layout of existing code and promote company standards. Even if 
I ate to the game, Delphi itself now includes code formatting capabilities, with 
enough f lexi bi I ity bui It i nto the system to make it worthwhi le (even i n what is 
clearly a fi rst attempt, but sti 1 1 a good one) . 
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The Code Formatter is i nvoked with the Format Source command of the local 
menu of the editor or with the correspondi ng Ctrl +Alt+F shortcut. I f there is 
some text selected inthe editor, the formatting will be applied only to the selec- 
tion, if not to the enti re source code fi le. There doesn't seem to be a di rect way 
to reformat the source code of all of the files in a project on opening the editor, 
although it might not be too difficult to write an IDE extension to accomplish 
this. 

Despite the fact that there are some Del phi source code formatti ng gui del i nes, 
it is very difficult to fi nd perfect agreement among different Del phi program- 
mers on how exactly the code should be written. Formatting is generally subject 
of i ntense debate. The new source code formatter i n Del phi 2010 provides 54 
different options to fine tune its behavior. Granted this won't satisfy one mil- 
lion different formatting styles (one for each Delphi developer!), but it comes 
reasonably close. 



Options 





3 T 


HTML Formatting 
ebSnap 

anslation Tools Options 
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Continuation indent 
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Indent Begin and End keywords 
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■ ■ Repository 








Indent blocks between Begin and End 
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J ■ Formatter 








Indent class definition body 
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Indent comments 
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Indent compiler directives 
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1 n d entation for c ase statements 










;■ Spaces 








Indent case contents 
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i - Line breaks 
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=■■■■ Capitalization 








Indent Else in case statements 


False 
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Indentation for labels 








J ■ Default 








Indent labels 


Decrease one indent 








J Diagram 




























I -■ Appearance 
1 |— Layout 
i - Print 






Continuation indent 

Defines additional indent that is added for continuation lines when an expression (etc.} i 
■continued on several lines.... 
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■ ■ View Management 















□K Cancel Help 



One of the goals is at least to let developer format source code usi ng the stand- 
ard style used within the VCL source code and for the code generated at design 
ti me. This is al most the case with absol utely mi ni mal exceptions, as long as you 
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keep the default setti ngs. You can see some of the options i n the screen shot i n 
the previous page, but I won't cover each of them i n detai I as they are quite 
i ntuitive and the hel p section at the bottom of the pane is quite informative. 

The proof of thequality of the code formatter would bein its actual use by the 
Delphi community, and although I anticipate this feature will find its strong 
detractors, I've had a limited but positive experience with it (using itto cleanup 
the source code for thisbook) and think that a fair number of developers will 
get used to it. 

By the way, I find it quite odd that there isn't an option to apply the active 
formatting style to all files of a project. Doing this unit by unit can be extremely 
tedious. 

Live Templates and Code Completion 

There are some very mi nor i improvements to refactori ngs and I i ve tempi ates, 

including three new live templates, in Delphi 2010. All of them arequite trivial. 

There i s a r a i s e tempi ate and a t o d o tempi ate, produci ng the fol I owi ng two 

I i nes of code respecti vely: 

rai se Except i onType. Createf 'Error'); 
{T0D0 -oOwner -cGeneral : Ac t i on 1 1 em} 

The third new live template is a variation of the class declaration, called 
c I a 5 s f , which produces the same code of thee lass template without com- 
ments in each section. 

Speaki ng of refactori ngs, even if there are no brand new capabi I ities it is cer- 
tainly worth noting that the Rename, Change Parameters, and Extract Method 
refactori ngs now work on generic types. 

Finally, you can add the reserved words to Code Completion, by enabling the 
"Show reserved words" check box of the Editor Options | Code I nsight page of 
the Options dialog box. Thisoptions becomes handy when you have to type 
some rather long reserved words likei n i t i a I i z a t i on orresourcestri n g . 
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The Project Manager 



There areenough small changes in the Project M anager to devote a small sec- 
tion to it. Being one of the most commonly used panes of the IDE, even minor 
changesin it become significant. Before we look into this, let me underline that 
project files (the new . dproj format used by MSBU I LD and introduced in 
Delphi 2007) remain identical to Delphi 2009, to the point that they even carry 
the same version number 12.0. The actual version number of Delphi 2010, in 
fact, is 14 9 . 

This is a snippet of theinitial section of anew Delphi 2010 project file includ- 
ing the version information: 

< P r o j e c t x ml n s = " h 1 1 p : / / s c h e ma s . mi c r o s o f t . com/, . . ms b u i I d " > 
<Pr oper t y G r o u p > 

<Proj ectGui d>{F7C0ED24- 7449. . . }</Proj ectGui d> 

< P r o j ectVersi o n >1 2 . 0 </ P r o j ectVersi on> 

< Ma i nSource>Si mpl eTest . d p r </ Mai nSource> 
<Confi g Condi ti on="' $ ( C o n f i g)' ==' ' ">Debug</Confi g> 
<DCC_ DCCCompi I er>DCC32</ DCC_DCCCompi I er> 

</ Propert yGroup> 

The fact that there was no change i n the version number means you can di r- 
ectlyopen Delphi 2009 projects in 2010 and vice verse, with no conversions or 
any hidden changes. 

After this brief i ntroduction to the project fi les format, here are the new fea- 
tures of the Project Manager: 

• Where there are multiple projects open in 
the Project Manager, the project group 
local menu will also have the Compile All, 
Build All, and Clean All commands, as 
shown hereon the side. Individual project 
nodes have a new From Here menu item, 
with a sub-menu hosting the three Compile 
All From Here, Build All From Here, and 
Clean All From H ere commands. 



B- ijp Simplel 
[£ht^ Bull 
B- U sim 

B |jp Praje< 
Buil 

B H Uni 



Compile All 
Build All 
Clean All 

Add h[ew Project... 
Add Existing Project... 

Save Project Group 
Save Project Group As... 

Rename 



9 The reason the Delphi internal version number (not to be confused with the compiler 
version number, which is currently at 210) jumped from 12 to 14, is the same you won't 
find floor B in a US hotel or row 13 on a plane: that number is associated with bad luck! 
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• You can drag a fi le from the editor to the Project M anager wi ndow to add it 
to the current project. 

• The local menu of a project has a new Sort By menu that let's you sort the 
project's units by Name, Modified Date, Type, or Path. If you keep the Auto 
Sort option on, the setting will be applied to any new unit added to the pro- 
ject and i n case status of a unit changes. I f Auto Sort is off, the sorting 
option you enable will be applied only once. In case you manually reorder 
one of the units of the project, theAuto Sort options will be turned off. 

• The Project Manager toolbar has a sort button that let's you define the sort 
order for al I of the open projects and also preset some default sort options. 

• I n case of package projects, there is a new Uninstall menu. Notice that you 
don't generally need to use this command, as when you Compileor Build a 
package, if this is already installed it will be automatically uninstalled before 
compiling it and reinstalled after the compilation. I n specific circumstances, 
though, it is handy to remove a package di rectly from the Project M anager. 

• Noticealsothatdependingwhetherthepackageisinstalled or not g$ Pr0 j ei 
itsicon in theProject Manager changes, with the small gear turn- _ ^ e 
ing from gray (not installed) to yellow (installed). This icon with 

the gear is used by design ti me packages, whi le run ti me packages 
have the base icon with no gear (they cannot be installed in the IDE). 

• By the way, you can now also select multiple packages in theProject Man- 
ager and perform an Install operation on all of them at once, using the local 
menu of the Project M anager. 



Build All and Active Project 

There is another significant change (which I don't I ike really) inthewaythe 
project manager behaves when building multiple projects. What used to hap- 
pen when doing a Build All was that each project would become the active 
project in turn and you could use this visual clue to seethe progress of along 
compilation. Now you get information about each project while it compiles, but 
no overall view. 

Another difference, and possi bly the reason for this change, is that at the end of 
the multi- project compilation the current project doesn't change. If you debug 
a project, do a rebuild all, and than start debuggi ng again you'll be working on 
the same project, regardless of their sequence. This is actually quite nice, but I 
wish the two effects (display the current project being compiled, plus restoring 



Marco Cantu, Delphi 2010 Handbook 



36 - Chapter 1 A Better IDE 



the one you were working on at the end of the compilation) could be combined, 
rather than addi ng one at the expense of the other. 



The Object I nspector 

Even if the changes to the Object 
Inspector in Delphi 2010 are limited, 
they are certai nly worth a look, consider- 
i ng that this is a wi ndow developers 
generally spend a lot of time working 
with. The first noticeable change is the 
new property editor for Boolean values, 
which displays a check box you can use 
to toggl e the val ue (although the drop 



|f( Object Inspector 



Form39 TForm39 
| Properties | Events I 



Action 

ActiveControl 
Align alNone 
AlignWithMargin □ Fat 
AlphaBlend □ False] 

AlphaBlendValue 255 
Anchors 
AutoScroll 
AutoSize 



[akl_eft,akTop] 
■s True 

□ False 



down list with True and False is still available). 



Object Inspector 



Form39 TForm39 
| Properties | Events I 
Action 



ActiveControl 
Align 



alNone 



All shown 



13 



The Description Pane 

Two more changes are visi ble at the bottom of the Object I nspector. Fi rst, there 
is now a Descri ption pane at the bottom of the Object I nspector. This pane (ori- 
gin ally introduced inthelDE during the devel- 
opment of Delphi for .N ET) is supposed to show 
information about the current property, but all it 
does is repeat the property name. This seems 
quitea waste: You can reduce its size to a single 
line(oreven less than a line), butthereisno 
obvious way to remove it altogether. 

Si nee I really don't like it, I've written a small 
informal 10 1 DE plugin to get rid of it. The unit 

that removes that pane is part of the Customl nsight package. I n its R e g i s t e r 



□ 



10 An informal plug-in of the Delphi I DE, in my personal jargon, is one that doesn't use the 
Open Tools API but manipulates I DE object directly, something that can easily be done 
considering the Delphi is itself a VCL application, so you can reach for the global 
Ap p I i c a t i on and Screen objects and ... look around. 
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procedure it looks for the Object I nspector wi ndows by scanni ng the 

Screen. F o r ms list, finds the component called DescriptionPane, and sets its 

H e i g h t property to zero. The skeleton of the code (without some of the needed 

tests) is the foil owing: 

function Fi ndObj ectl nspector: TComponent; 
va r 

I : Integer; 
begi n 

Result : = ni I ; 

for I := 0 to Screen. For mCount - 1 do 
if Screen. For ms [ I ] . CI assName = 
' TP r o pe r t y I ns pe c t o r ' then 
Exit (Screen. For ms [I]); 

end; 

procedure Regi st er ; 
va r 

aComp: TComponent; 
begi n 

aComp : = FindObjectlnspector; 

aComp := aCo mp. Fi ndCo mp onentf ' De scr i pt i on Pa ne')\ 
(aComp as TControl). Height : = 0; 
end; 



The Component Editor Pane 

The second new pane is an area devoted to the component editor menu items, 
following the style used by Visual Studio. Traditionally in Delphi component 
editors (that is, special actions you can perform on given components at design 
time) showed up in the local menu of the 
desi gner, once the component was selected. 
Now, while the commands in the local menu are 
still there, the same information is visible in 
another pane at the bottom of the Object 
I nspector, as you can see here on the side for the 
ClientDataSet component 11 . This new user inter- 
face makes the component editor commands 
easier to reach not only for developers using 
Visual Studio, but even for most existing Delphi 



11 Notice that in this case I 've removed the Object I nspector status bar and reduced the De- 
scription pane to the mini mum, without using the I DE plug-in covered earlier. 
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Active 

Aggregates 
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CommandText 
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□ 
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□ False 
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Fields Editor... Fetch Params 
Assign Local Data... 
Load from MyBase table... 
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users, as you often could only use the component local menu to figure out if a 
edi tor was avai I abl e, wh i I e now thi s i s cl earl y vi si bl e once a component has 
been selected. 

Notice you can now select the component with the combo box of the Object 
I nspector and activate its Component editors, without havi ng to make it visi ble 
in a designer as it was the case until Delphi 2009.The Return of Component 
Toolbar 



Other I DE Features 

Beside the new I DE I nsight capability and the new features that relate with the 
editor, there are other changes that are worth highlighting, from background 
compi lations to the Components tool bar. 

Background Compilation 

Whi le in the past compi I i ng a large appl i cation would force you to stop usi ng 
the IDE while the operation was taking place, in Delphi 2010 you can turn on 
background compilation. This is not meant to speed up the compilation, but 
only to avoid blocking the IDE while doing so. 

Considering Delphi compilation speed, this is hardly noticeable for the average 
application, but when compiling a large project group that takes sometime it 
certainly can be nice to keep working while Delphi is compiling. When you turn 
on this setting, keep in mind that Delphi will take a sort of snapshot of the files 
in the editor during a background compilation, so that the changes you perform 
after issuing a compilation request won't be seen by the compiler. 

H ow can you take advantage of this feature? An example would be looki ng at 
the source code files for warnings the compiler has already issued, while it 
keeps compi ling. Another options could be adding breakpoints. You can also 
edit files, but this won't make a lot of sense if you plan debugging your program 
after you've compi led it. I n fact, when you issue a Run (or F9) command, back- 
ground compilation won't be used, regardless of your settings. The same 
happens for a Step Over (F8) command. 
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Still, running a compilation whileyou keep writing more code wi 1 1 reduce fol- 
lowing compi I e ti mes and ( at ti mes) i mprove the reliability of the Code I nsi ght 
information, I ike Error Insight. 

I n any case there is a long list of other operations you cannot do during a back- 
ground compilation, from changing compiler options to closing a project or 
activating another one, from using any refactoring to executing another compil- 
ation, from installing packages to starting the debugger. The full list is available 
in the Delphi 2010 help file under: 

| ms- hel p: / /embarcadero. rs2010/rad/Background_Compl I a t i on. html 



The Return of the Component Toolbar 

I n Del phi 20 10 there i s now an opti on to di spl ay the components vi si bl e i n the 
Tool Palette in a toolbar below the main menu 12 . This is extremely similar to 
how the Component Tool bar used to look like in Delphi 7 and before), and the 
feature has been specifically added asa way to convince some of the Del phi 7 
aficionados to mi grate to a new version: 



© Project33 - Delphi 2010 - Unit4Q 
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You can actually go to some extreme and make Delphi 2010 look almost exactly 

like Delphi 7. This was covered in a short video byAndreano Lanusseof 

Embarcadero Technologies at: 

http: / /bl ogs. embarcadero. com/andreanol anusse/how-to-confi gure 
-dei phi - 2010- to- I ook- work- and- feel -I i k e - del phi - 7/ 

The new tool bar, vi si bl e i n the i mage above, has the cl assi c tabs to pi ck on of 
the pages plus a local menu with the tabs in alphabetic order 13 and a Search box 
active I ike a component filter (removing pages with no matching components). 



12 The code of the new Component Tool bar was ori gi nal I y part of the "Andy's D DevE xten- 
sions" and was donated to the product by Andreas Hausladen. 
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You can drag the tabs to reorder them (they'll start by matching the sequence in 
the Tools Palette). 

There is also a specific page of the Options dialog that you can use to fully cus- 
tomize and configure the Component Tool bar, as you can see below. Notice that 
if you change the Component Toolbar configuration, this won't stay in sync any 
more with the Tools Palette, which is the default behavior. 





Options 



Environment Options 
Object Inspector 
Tool Palette 

; - Colors 
Component Toolbar 
Environment Variables 
Reopen Menu 
Explorer 
Delphi Options 
Type Library 
Library - Win32 
Library -Translated 
VCL Designer 
tor Options 
Source Options 
Color 
■ Display 
Key Mappings 
Code Insight 
HTML Options 

HTML Formatting 
WebSnap 

Translation Tools Options 
Color 



Edi 



Pages 



System 

Additional 

Win32 

Win 3. 1 

Data Access 

Data Controls 

Dialogs 

Indy Misc 

dbExpress 

Datasnap Client 

Datasnap Server 

BDE 

Vista Dialogs 
Touch 
Gestures 
DataSnap Client 
Indy I/O Handlers 
Indy Clients 
Indy Servers 
Indy Intercepts 
Samples 
Internet 
InternetExpress 
WphSn^n 



Components: 


Name 




Page 


Pad 


El Frames 




Standard 




HP TMainMenu 




Standard 


dds 


El^ TPopupMenu 




Standard 


dds 


^ TLabel 




Standard 


dds 


[*3 TEdit 




Standard 


dds 


(H TMemo 




Standard 


dds 


[ojD TEutton 




Standard 


dds 


|xj TCheckBox 




Standard 


dds 


® TRadioButton 




Standard 


dds 


H TListEox 




Standard 


dds 


H TCornboBox 




Standard 


dds 


ana TScrollBar 




Standard 


dds 


TGroupBox 




Standard 


dds 


g} TRadioGroup 




Standard 


dds 


[J TPanel 




Standard 


dds 


TActionList 

* u 


rrr 


Standard 

i 


dds 
f 



Add. 



Delete 



Move Up 



Help 



Speaking of the Tools palette, you can now rename Palette categories (like 
those hosti ng the components) usi ng a new correspondi ng menu. The Palette 
has another new feature: it remembers the current position (with the current 
open categories) when switching designers. 



13 In case you are wondering what the Win 3.1tab is for, its hosts a set of very old VCL con- 
trols that pre-date Windows 95 and have been kept around for compatibility reasons. 
Nothing to do with the development of 16- bit applications for Win 3.1, a feature available 
only in the first version of Delphi, many years ago. 
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Many More Recent Files 

In Delphi the lists of recent projects and files have always been limited toa 
fixed size, 5 for projects and ID for files (units). Now in the File | Reopen menu 
you can pick the Properties command and open up a configuration dialog box, 
which lets you both change that number and and clean upthelist, by removing 
non-existing files and individual entries you don't care about: 



Reopen Menu Properties 
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Number of projects: 
Number of files: 

Reopen items 
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Delete Nonexistent Files 



Delete 



Clear 



OK 



Cancel 



Help 



Although this is a nice addition, I thinkl'd still prefer using the project man- 
agement features of the Welcome page, which let's you pick specific projects 
and mark them as favorites, so that they remain availableover time. I n the 
Welcome page you can also group favorite projects and manage these categor- 
ies. If you are used to that (like I am), the extensions to the recent files will help 
you only with individual files and units, not with projects. Though using both 
techniques together gives the best of both worlds. 

Keep in mind, though, that the recent files can be stored on a project by project 
basis, when you let Delphi save Project Desktop settings. I n this case the list of 
recent files depends on the active project, which is not a bad idea after all. That 
list, though, cannot be managed in the same way of the global one. 
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There is a problem that might happen if you increase the number or files or 
projects and your screen has a limited resolution. I n case the second level menu 
with the list of projects and files doesn't fit on the screen, it will simply not 
show up at all (rather than showing a partial list) ! This is a bug of the PopupAc- 
tionBar control used by the IDE and the only workaround is to reduce the 
number of items i n the I ist. 



Use Unit Dialog 



Among the dialog boxes that have been made to look more modern, there is 
certainly the Use Unit dialog box, displayed belowin both the Delphi 2010 and 
"classic" Delphi 2009 versions. This dialog box also shows a small new feature, 
the abi I ity to add the unit you are i nterested i n to the uses statement of the 
i nterface section of the current unit or to the uses statement of the 
i mpl ementati on section (which was theonly option in the past). Again, you 
can now search a unit with the filter at the top of the dialog box. 



Q Use Unit 



fiUniWl.pas [Ci'^JsergWarcopocuments^AD Studio ^Projects) 



"SI Use Unit 



"I I 



0 K 



Help 



Add to: Interface '^'Implementation 

OK Cancel 



Updates to the Gallery 

The last dialog box that I want to mention istheGallery, or New Itemsdialog 
box. As many other wi ndows, it now has a search box to fi Iter its content (con- 
tent that also shows up in IDE Insight), but also has some changes in its 
behavior. 
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(1$ New file 



I 23 I 



Select extension or type: 



Extension 
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n 



r 



Or enter any extension: 



0 Add new file to current project 



Cancel 



Rather than showing only the avail able options for the current context, as 
happened inthepast, theGallery now shows all of the possible new items: 
those not availablefor the current context are grayed out. This makes it easier 
for users to find things, and also to figureout what is currently not available. In 
the past, at ti mes one had to go through many pages looki ng for somethi ng that 
was si mply not there because it was not avai lable for the current context. 1 1 
used to be quite annoyi ng. 

Another update to the New 
Items dialog box relates to the 
selection of a new text file 
(Other Files | Text File). Rather 
than si mply opening a new 
blank text file, the Del phi IDE 
now asks for an extension and 
whether you want to add the 
fileto the project. This way 
adding an .INI file, an XML file, 
or other configuration fileto 
your projects becomes easier. 
The New file dialog box has the 
I ong I i st of extensi ons parti al I y 
visible in the image on the side. 

The I i st of extensions can be 

modified using the same dialog box and isstored inthe Registry using theExts 
key under: 

H KE Y_ CURRENT, US ER\ Sof t war e\ Co d e Ge a r \ B D 5 \ 7. 0\ TNe wF i I e D I g 



View Messages 

The View menu has a new command, View | Messages, that lets you open the 
message pane at the bottom of the editor. When you compi le a program that 
has errors or warnings, that pane is opened automatically. In case there are no 
errors, you might still want to look at the information about the compilation 
added to the Output tab (with the command line executed for compiling) or the 
Build tab, I ike the foil owing: 
| Checki ng project dependencies... 
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[Compiling Project33.dproj ( Debug configuration) 
I Success 
Elapsed t i me : 0 0:0 0:0 1,2 

Oddly enough, si nee this output was added in Delphi 2007, there was no way to 
see it for a successful compilation (unless the Message pane was already open 
because of a previous compilation error). 



What's Next 

I n this chapter I focused on the new features of the I DE and the editor of 
Delphi 2010, butl actuallyskippedasignificantareaofthelDE,thedebugger. 
The reason is that there are quite a few interesting new features for the debug- 
ger, so I wanted to devote its own chapter to this specific topic. 

I n Chapter 2, 1 won't si mply look at new features of the debugger but wi 1 1 also 
cover new debugger customizations. 
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Chapter 2: The 
Debugger 

One area of the Del phi Integrated Development Environment that has seen a 
significant number of i improvements is the Integrated Debugger. This is one of 
the reasons why I decided to devote a specific chapter to this topic even if it is a 
short one. 

The second reason is that the Del phi Debugger is more powerful than most 
developers realize and it often an underused area of the product, with many 
littleknown features, and by covering it specifically I hope to reverse this trend. 

I'll start the chapter with a new nifty feature, dragging the instruction pointer, 
look at various U I and functional changes, and spend the fi nal part of the 
chapter focusi ng on the new debugger visual izers. 



Dragging the I nstruction Pointer 

Wehaveseen in the last chapter that in gutter of the Del phi editor you can now 
drag bookmarks and also breakpoints. This can be useful, but is not that 
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important, as creating a new bookmark or thread isgenerallyamatterof aclick 
(although a bookmark with complex rules will take some time to configure). 

A similar dragging operation is also available (believe it or not) for the instruc- 
tion pointer (or IP). This means that while you aredebugging an application, 
you can move the i nstruction poi nter forward, ski ppi ng some statements or 
move it back, executi ng a statement a second ti me. I n between, of course, you 
can alter a local variable or perform other operations as usual. 

Let me illustrate this new feature, that I find extremely powerful, with an 

example. Suppose you have this code (which ispartof theMovelP demo); 

procedure TForm3 9. ButtonlCI i ck( Sender: TObject); 
var 

X, Y: Integer; 
begi n 

X : = 100; 
Y : = 50; 
Left : = X; 
Top : = Y; 
X : = X + Y; 

(Sender as TBut t on) . Capt i on := IntToStr (X); 
end; 

I f you pi ace a breakpoi nt on the f i rst I i ne, and start steppi ng i nto the statements 
(pressing F8), you can get to the line in which you add X and Y, as in thefollow- 
i ng i mage: 




(Sender as TButtori) . Caption := IntToStr (X) ; 
end; 



Now you can press F8 again, to execute that line, move the mouse over the 
instruction pointer (the I eft- to- right light blue arrow), drag it back to the addi- 
tion, and repeat the process a few ti me. This way you can execute the same 
statement multiple times, i ncreasing the value of X. In more practical situ- 
ations you can repeat an operation after changing some variables rather than 
havi ng to stop the program and restart debuggi ng. I n real world situations get- 
ting back to a given method can take quite some time. 
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Another option would be to pi ace the same breakpoint, execute the initial 
assignment of X, move the instruction pointer to the addition (skipping the ini- 
tialization of Y and the property assignments), to see what it happens in the 
program. At ti mes, it might be very handy to ski p some operations and test the 
followi ng ones. 

J ust for fun, you can also go back to the statement addi ng X and Y, execute it, 
move the instruction pointer back to the original assignment of X, then bump it 
to the final line, and display 100 in the button's caption. 

In theory you can even drag the instruction pointer to a different method, in 
which case the debugger will show 
you the warning displayed hereon 
the right side. I n most cases, 
though, this will result in an 
access vi ol ati on as the sped f i c 
code is not properly initialized 
and cannot be executed. 

Again, being able to change the execution flow of a program without having to 
stop the debugger, actually edit the code, recompile the program, and restart 
debugging getting the program again in the same status is an extremely signi- 
ficant step forward for the debugger. I n my view, this is one of the most useful 
new features of Delphi 2010, but it seems that it was somewhat neglected in 
terms of documentation and product marketing. 



Warning 



1 - £5 " I 



This operation will set the next statement to a different 
function, Set the next statement to this location anyway? 



Yes No 



Small Ul Changes 

In general, Delphi 2010 sees quite a few changes in terms of the debugger user 
i nterface i n addition to its new capabil ities. H ere I 'm providi ng j ust a very short 
overview. The Event Log view uses an optimized Virtual Tree View component 
and adds support for multi- line output from Out put DebugSt r i ng calls and 
exception messages. I n the same pane, when auto scrolling is enabled, you can 
temporarily disable scrolling by clicking on the pane, and resumeit by selecting 
the I ast item ( pressi ng the E nd key) . 

Inthelocal menus of the Local Variables view, the Watches view, and the 
Debug I nspector pane, there are new commands for openi ng the 
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Evaluate/ Modify dialog box for the given symbol or expression and for creating 
a new watch. 

There are changes also to the CPU view, with the option of "following" 
registers, but detai Is are relevant only to those who know how to use this 
debugger view (which areaveryfew, myself excluded). Another small but 
i nteresti ng change is that the debugger tries to remember the expanded status 
(that is, if you've expanded any of the properties or ancestor objects) of 
watched variables and variables in the Local view. Next time you stop at a 
breakpoint, the previous situation will be restored if possible. 14 



Debugging Threads 

If debugging applications can at times become a very complex task, debugging 
multi-threaded applications is always complex and can become a daunting 
activity. The debugger, in fact, interferes with the flow of execution of the 
threads, for example slowing the thread that is being stepped into. Also while 
you are debugging a method you've placed a breakpoint in, other threads might 
need to call the same method, causing a great deal of confusion. 

To help you out a little bit (making things a little more manageable, even if still 
very complex) the debugger in Delphi 2010 introduces a few thread-oriented 
operations. 

First, when you set a break- 
point you can tie it to a 
specific thread. This is partic- 
ularly handy when placing a 
breakpoi nt i n a method or 
routi ne executed by multiple 
threads. If you name the 
threads, you'll seea list with 
the names of the active 
threads, as i n the i mage, 



Source Breakpoint Properties 



I n l 



Filename: 
Line number: 
Condition: 
Thread : 
Pass count: 



C: \Users\Marco\poajments^AD Studio \Projects\ t 



23 



□ 



Advanced » 



OK Cancel Help 



14 M ore i nformati on about the fix to this I ong-standi ng i ssue i n Chri s H esi k bl og at: 
http:// blogs.embarcadero.com/ chrishesi k/ 2009/ 10/06/ 34989 
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which will remain valid for foil owing debug sessions. If the threads have no 
name, you'll get the I Ds of the threads being executed. The option to specify a 
given thread for a breakpoi nt is avail able for Source Breakpoints (the com- 
monly used ones), the Address Breakpoints, and also for Data Breakpoints. 

Once a thread (the main thread or a secondary one) is stopped in the debugger, 
you can take control of the threads' execution. I n the Thread Status View pane, 
in fact, you can use new local menu commands for freezing and thawing (that 
is, unfreezing) a given thread or all threads except the current one: 



Thread Status 

Thread Id State Status 

^ NamecTThreads.exe (8,,, 

C^jMjin (SoO.) 5t'3pp?d ET^akpomt 

% MyThread (5992) Stopped Frozen 




Thaw 

Thaw All Thread: 

Process Properties 

Stay on Top 
■/ Dockable 



As you can see i n the previ ous i mage, the status of the thread named M yThread 
isnow frozen, after calling the Freeze command for the given thread. 

For experi menti ng with threads i n the 
debugger I 've create a basic application 
that uses named threads, called Named- 
Threads. 

If the ability to create named threads 
was already in Delphi 2009, the code 
generated by the Thread Wizard of the 
N ew I terns di al og box i s consi derabl y 
different. In Delphi 2009 the code of 
your named thread will include the fol- 
lowing: 

I procedure T My Thread. Set Na me; 
va r 
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Thread Name: MyThread| 



Cancel 
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ThreadNamelnfo: TThreadNamelnfo; 
begi n 

Thr eadNamel nfo. FType : = $ 1 0 0 0; 
ThreadNamel nfo. FName := 'My Thread'; 
Thr eadNamel nf o. FThr eadl D := $ F F F F F F F F ; 
ThreadNamel nfo. FFI ags : = 0; 

try 

Rai seExcepti on( $406D1388, 0, 

sizeof(ThreadNamelnfo) div sizeof(LongWord), 
©ThreadNamelnfo ); 
except 
end; 
end; 

procedure TMyThread. Execute; 
begi n 

Set N a me ; 

{ Place thread code here } 
end; 

Now the same code, in Delphi 2010, is part of a new class method of the 

TThread class, called Na meTh r e a d F o r Debuggi n g , so the same code becomes: 

procedure TMyThread. Execute; 
begi n 

NameThreadFor Debuggi ng( ' MyThr ead' ) ; 
{ Place thread code here } 
end; 

The same class method can also be called from the main thread, to give it a 
thread name like "Main". Again, doing so let's you refer to the mai n thread in a 
standard way between consecutive debug sessions. 

Getti ng back to the N amedThreads example, it has a thread that computes a 

string with the current time by calling a trivial global function: 

function CurrentTi meAsStr: string; 
begi n 

Result : = Ti meToSt r ( Now) ; 
end; 

Thissinglelineof codeiscalled by both the secondary thread, in its own con- 
text, and by the main thread. Calling a synchronized method of the main form 
would have defeated the example altogether, as I need a single function called 
i n two different threads to demonstrate pi aci ng a thread-specif ic breakpoi nt. 

The thread callsthe function is a loop that keep going until itsTermi nate flag 
isset and uses an anonymous method for synchronizing (again calling the 
CurrentTi me As S t r function within the synchronized code would have 
defeated the purpose of this example) : 
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procedure TMyThread. Execute; 
va r 

s t r T i me : String; 
begi n 

NameThreadFor Debuggi ng( ' MyThr ead' ) ; 
FreeOnTermi nate := True; 

whi I e not Ter mi nat ed do 
begi n 

sleep ( 1 0 0 0 ) ; 

strTime := CurrentTi meAsStr; 
Synchroni ze(procedure () 
begi n 

FormNamedThreads. Log ( ' MyThr ead: ' + s t r T i me ) ; 
end) 
end; 
end; 

The global function Cu r r en t Ti me As St r is called also by the main thread in the 

handler of an On Ti mer event: 

procedure TFormNamedThreads.Ti merlTi mer(Sender: TObject); 
begi n 

Log {'Main: ' + Cu r r e n t Ti me As St r ) ; 
end; 

Other than that, the main form has code for creating and freeing a single 
instance of the thread object. You can experiment with this project by placing a 
breakpoint in theCu r r en t Ti me As St r function and try stepping into the first 
thread that stops, f i rst with no freezi ng and I ater freezi ng the other thread. 
Notice that if you freeze the mainthread,theSynchroni ze call won't return 
(because it needs to execute code in the context of the main thread, which is 
blocked), effectively blocking also the secondary thread. In this case (with no 
thread blocked in the debugger), you cannot thaw the frozen thread. What you 
can do, instead, is pause the program: at that point theThread Status View will 
let you issue the various freezing and thawi ng commands. 



Debugger Visualizers 

Another useful changein the architecture of the Del phi debugger isthe ability 
to plug in specific visualizers for complex data structures. For example in the 
past when looki ng at a T D a t e T i me variable, you'd see its i nternal floati ng poi nt 
value. In Delphi 2010, instead, one of the pre- installed visualizers lets you see 
the date and time value in a specific and more meaningful way. This is quite 
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obvious if you compare the Delphi 2009 view of a local T Da t e T i me variableon 
the left with the Del phi 2010 one on the right: 



Local Variables 



DebugVisualMainForm.TForm 39. Button lClick[sl6E 



Name 

B Self 
Sender 
theTime 



Value 

[[cslnheritable]. False, {0, 
0 

40037,669597 



Local Variables 



| Unit39 .TForrn 39 , Button lClidt(51B 5A8C0) 

Name Value 

Eg Self ([cslnheritable], False, (0, 

Sender 0 

theTime 8/12/2009 4: 0 1: 27 PM 



You can see this visual izer by experi menti ng with the DebugVisual project of 
the current chapter. There aren't many such visualizers pre- installed in the 
Delphi IDE. One of them istheTDateTimeVisualizer, and the other isa 
TStrings Visual izer, as you can seein the new page of the Options dialog 
(Debugger Options | Visualizers) showing the visualizers configuration: 

Registered Visualizers 



TDatETime/TDatE/TTime Visualizer for Delphi and C++ 



!ii std::string and stdnwstring Visualizer for C++ 
-J TStrings Visualizer for Delphi 



The good news, however, is that third parties can build and plug- in their own 
custom visualizers into the I DE. You can do the same for any specific data 
structures you tend to work with. The two predefined visualizers are examples 
of the two different kinds of visualizers available in Delphi. A value replacer, 
like theTDateTi me Visualizer displayed earlier, shows its valuedirectly in 
pi ace of the def au 1 1 one the debugger woul d di spl ay ( i ncl udi ng the E val uator 
Tooltips, the Watch View, the Locals 
View, the Evaluate/ Modify dialog, and 
the Debug I nspector View. An 
external viewer, I ike the TStrings 
Visualizer shown in action hereon the 
right, adds to the default debugger rep- 
resentation a magnifying glass icon, 
which brings up a menu with a view 
command. 

Activating this command opens up a separate wi ndow, which can generally be 
docked alongside the others panes of the IDE. This is the viewer of the 
TStringsVisualizer, the only one external viewer supplied with Delphi 2010: 



\.\ Local Variables 


0Sii 


|DebugVisualMainForm.TForm39.Button2Click(sl70ABA0) ▼ | 


Name 


Value 


g- Self 


[[cslnheritable] , False, (0, 0), (331, 2... 


Sender 


0 


j— si 


o 1 



Show Strin 



3» 
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TStrmgs Visualizer far si 




Index 


Value 




[0] 


1 




[i! 


2 




[2] 


3 




[3] 






[4] 


5 




[5] 


6 




[6] 


7 



Advanced: Visualizer Internals 

Warning: This and the next are two advanced sections using the Open Tools 
API . I f you are not i nterested i n extendi ng the Del phi IDE or have never used 
such a low-level API, you might want to skip the remainder of this chapter. 

With only two visualizers available, it is quite clear that what is important is the 
plug-in ability, and the possibility for a power user to configure this feature 
more than what's already in the box (and also to distribute its visualizers just 
like other IDE extensions). This is why it is worth looking behind the scenes, 
opening up another new area of the Open Tools API, just I ike I did in Chapter 1 
regarding customization of the IDE Insights. 

Thisti me less effort isneeded, because Delphi 2010 ships with the complete 
source code of its two ready-to-use visualizers, which provide good blueprints 
for experiments. The code is in the Wi n 3 2 \ V i s u a I i zers section of the source 
code that comes with the Delphi installation (under Embarcadero\RAD 
St udi o \ 7 . 0 \ source). 

If you look in theToolsAPI unit (the unit hosting most of the Open Tools API 

interface), you can see that the I OTADebuggerServi ces interface has a new 

method for i nstal I i ng a vi sual i zer i n the I D E : 

procedure Regi st er DebugVi sual i zer( 

const Visualizer: I OTADebuggerVi sual i zer) ; 

The parameter is an object implementing the I OTADebuggerVi sual i zer 
interface, which provides the overall information about the visualizer I ike its 
unique name, a description, and the data types to which it can be applied. The 
visualizer object must also implement one of the two specific i nterfaces for the 
two types of visualizers I mentioned earlier: 
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I OTADebuggerVi s u a I i zerVal ueRepI acer 
I OTADebuggerVi s u a I i zerExternal Vi ewer 

The first has a method receiving a string with the value to be evaluated and 
returning a different one, after some custom processing; the second has a 
method to let you add an entry to the type inspection menu item and a second 
method executed when the menu item is invoked. You can have only one value 
replacer for each data type, whileyou can have multiple external viewers. 

Building an external viewer is morecomplex, as you'll have to integrate the 
user i nterface with the I DE, providi ng docki ng support by i mplementi ng the 
other Open Tools API interface, and provide a way to refresh the output 
dependi ng on the status of the debugger. You obtai n this i ntegration by i mple- 
mentingthel OTADebuggerVi sual i zerExternal Vi ewerUpdater interface, 
which has four rather complex methods. That's why here I 'II buildavalue 
replacer 15 . 



Building a Value Replacer for UCS4Char 

Before we delve i nto the development of a debugger visual izer, let me poi nt you 
to a specific situation in which the debugger provides limited information 
about the values of a type. Consider the foil owing code snippet, which is part of 
the DebugVisual example which is also used to demonstrate the other debugger 
visualizers. 

procedure TForm3 9. btnUcs4CharCI i ck( Sender: TObject); 
va r 

ch: UCS 4C h a r ; 
begi n 

ch : = Ord ('(>'); 

ShowMessage ( Ch a r a c t e r . Co n ve r t F r o mLIt f 3 2 (ch)); 
end; 

If you put a breakpoint in the code above and look to the value of c h , you'll see 
its numerical value, not the character is 

represents, as shown on the right. 1 1 ^ Local VariaWes &M 
would be nice to see the accented letter, l^ugv-^MainFonn.worw^.b^u^b^cmt^^ - \ 

Name Value 

something we can now do thanks to this ® s^f a^^m.^Ao.o), (423,3... 

Sender 0 

new feature. l * 



15 Refer to the source code of theTStringsVisualizer for an example of the other type 
(which is certainly more interesting, but also quite complex). 
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To i nstal I a custom vi sual i zer we have to create a desi gn ti me package that 
requires the des i gni de. dcp packageand add aunit with a class implement- 
ing two debugger vi sual i zer interfaces (the base one and the specific one) plus 
thel OTAThr eadNot i f i er interface. 

The cl ass must provide al I of the methods ( here grouped by i nterface) , even if 
most of them will have an empty implementation: 

type 

TDebugger Ucs4CharVi sual i zer = class ( 

Ti nterfacedObj ect, I OTADebuggerVi sual I zer, 

I OTADebuggerVi sual I zerVal ueRepI acer, I OTAThreadNotl f i er) 

publ i c 

{ I OTADebuggerVi sual i zer } 

function Get Support edTypeCount : Integer; 

procedure Ge t S uppo r t e d T y pe( I ndex : Integer; 

var TypeName: string; var Al I De s c e n da n t s : Boolean); 



f unct 
fund 
fund 



on GetV 
on GetV 
on GetV 



sual 
sual 
sual 



zerldentifier: string; 
zerName: string; 
zerDescri pti on: string; 



{ I OTADebuggerVi sual i zerVal ueRepI acer } 
function Ge t R e p I a ce me nt Va I ue( cons t Expression, 
TypeName, EvalResult: string): string; 

{ I OTAThr eadNot I f i er } 

procedure Eval uteCornpl ete(const ExprStr: string; 
const ResultStr: string; CanModify: Boolean; 
Res u I t Add r e s s : Cardinal; ResultSize: Cardinal; 
Ret ur nCode: Integer); 
procedure Modi fyCornpl etefconst ExprStr: string; 

const ResultStr: string; ReturnCode: Integer); 
procedure ThreadNot i f y( Reason: TOTANo t i f y Re a s o n ) ; 
procedure Af t er Save; 
procedure BeforeSave; 
procedure Destroyed; 
procedure Modified; 
end; 

The methods implementing the I OTADebuggerVi sual i zer interface provide 

information about the debugger visual i zer, including the name and description 

that will bedisplayed in the Debugger Options | Visual izers page of the Options 

dialog box, covered earlier: 

fundi on TDebugger Ucs4CharVi sual i zer. 

GetVi sual i zerl denti fi er: string; 
begi n 

Result : = ClassName; 
end; 



fundi on TDebugger Ucs4CharVi sual i zer 

GetVi sual i zerName: string; 
begi n 
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Result := ' Ucs4Char Vi sual i zer for Delphi'; 
end; 

fundi on TDebugger Ucs4CharVi sual i zer. 

GetVi sual izerDescri ption: stri ng; 
begi n 

Result := 'Displays the Unicode string for a Ucs4Char'; 
end; 

Thelasttwo methods return thenumber of types the visual i zer can be used for, 
and each of their names (in thiscase, there is only one type, maki ng the code 
much simpler): 

functi on TDebugger Ucs4CharVi sual i zer. 

Get Suppor t edTypeCount : Integer; 
begi n 

Resul t : = 1; 
end; 

procedure TDebugger Ucs4CharVi sual I zer. Get Suppor t edType( 

Index: Integer; var TypeName: string; 

var All Descendants: Boolean); 
begi n 

Al I Descendants : = False; 
TypeName : = ' UCS4Char ' ; 
end; 

Theother relevant method is Get Re pi a c e me n t V a I ue of the specific interface 

forthistypeof visual i zer, I OTADebuggerVi sual i zerVal ueRepI acer : 

fundi on TDebugger Ucs4CharVi sual i zer. GetRepI acementVal ue( 
const Expression, TypeName, EvalResult: string): string; 
var 

ch: UCS 4Cha r ; 
begi n 

ch : = StrTol ntDef ( Eval Resul t, 0) ; 
Result : = C h a r a c t e r . C o n v e r t F r o mil t f 3 2 ( c h ) ; 
end; 

In this specific example, all of thel OTAThr eadNot i f i er methods have an 
empty body (but if you don't refer to that i nterface, the I DE wi 1 1 raise a low- 
level exception, so it is compulsory to have those empty methods). 

Now that we have a class implementing our debugger vi sual i zer for the 
U C S 4 C h a r type, we can install it after creating a global object, and clean up 
when the package is unloaded: 

var 

Ucs4CharVi s: I OTADebuggerVi sual i zer; 

procedure Regi st er ; 
var 

DebuggerServi ces: I OTADebugger Servi ces; 
begi n 
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Ucs4CharVis := TDebugger Ucs4CharVi s u a I I zer. Create; 
if Supports(Borl andl DEServi ces, I OTADebuggerServi ces, 
DebuggerServices) then 
DebuggerServi ces. Regi sterDebugVi s u a I i zer(Ucs4CharVi s ) 

end; 

procedure RemoveVi sual i zer; 
va r 

DebuggerServi ces: I OTADebuggerServi ces; 
begi n 

if S u p p o r t s ( Bo r I a nd I DE S e r v i c es , I OTADebuggerServi ces, 

DebuggerServices) then 
begi n 

DebuggerServi ces. Unregi sterDebugVi sual i zer( 

Ucs4CharVi s) ; 
FreeAndNi I ( Ucs4CharVi s) ; 
end; 
end; 

initialization 
f i nal i zat i on 

RemoveVi sual i zer; W^v**** 



DebugVisualMainForm.TForm39.btnUcs-KhflrClick(51A9AE8 



Name 


Value 


51 Self 


{[cslnheritable] , False, (0, 0), (169, 3, , , 


Sender 


0 


L di 


u 



After compiling the package with this 
unit and installing it, if you debug the 
same sample program again you'll see 
the Local Variables view hereon the 
right, including the accented letter 

assigned totheUc s 4Ch a r variable. This is much more informative than theori- 
ginal version 16 . It shows the value of installing similar in- pi ace viewers for any 
non trivial low-level data types or structures you are working with. 



What's Next 

I n thefi rst two chapters I 've provided you with a complete overview of the new 
IDE features in Delphi 2010. It is now time to move to another important topic, 
that is the changes in the Object Pascal compiler. The most significant new fea- 
ture of the compiler in Delphi 2010 is the support for Extended RTTI and 
Attri butes, a topic to which I 've devoted the enti re Chapter 3. 1 n the chapter 
after that I 'II touch on other interesting, even if less ground-breaking features 
of the compi ler and also focus on changes to the Run Ti me Li brary. 



16 This visual i zer will only work for Unicode characters that the default font can display. 
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Chapter 3: 
Extended RTTI 
And Attributes 



The area of the compiler that has seen the most significant update in Delphi 
2010 is the generation and management of Run Time Type Information, RTTI. 
Traditionally, compilers of strongly, statically typed languages, such as Pascal, 
provided littleor no information about the avail able types at runtime. All the 
i nformation about data types was visi ble only duri ng the compi lation phase. 

The first version of Delphi broke with this tradition, by providing run time 
information for properties and other class members marked with a specific 
compiler directive, publ i s tied . Thisfeature was enabled for classes compiled 
with a specific setting { $ M+} and is the foundation of the streami ng mechan- 
ism behind DFM files and the way you work with the form and other visual 
designers. When it was first made available in Delphi X this feature was a com- 
pletely new idea, and along the years other environment and development tools 
adopted and extended it in several ways. 
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First, there were extensions to the type system (avail able only in Delphi) to 
account for method discovery and dynamic invocation in COM . This is suppor- 
ted in Delphi by dispatch I D, applying methods to variants, and other COM- 
related features. Eventually COM support in Delphi was extended with its own 
flavor of run time type information. 

The advent of managed envi ronments, such asj ava and .N ET, brought forward 
a very extensive form of run time type information, with detailed RTTI bound 
by the compi ler to the executable modules and avai lable for discovery by pro- 
grams usi ng those modules. This has the drawback of unvei I i ng some of the 
program internals and of increasing the size of the modules, but it brings along 
new programmi ng models that combi ne some of the f I exi bi I i ty of dynami c I an- 
guages with the solid structure and the speed of strongly types ones. 

Whether you I i ke it or not (and this is i ndeed the subject of i ntense debate) 
Delphi is slowly moving into the same direction, and the adoption of an extens- 
ive form of RTTI in Delphi 2010 marks a very significant step in that direction. 
As we'l I see, you can opt out of the new RTTI , but if you don't you can leverage 
some extra power in your applications. 

The topi c i s far from si mpl e, so I wi 1 1 proceed i n steps. We'l I f i rst focus on the 
new extended RTTI that's bui It i nto the compi ler and the new classes of the Rtti 
unit that you can use to explore it. Second, I'll lookatthenewTVa I ue structure 
and dynamic invocation. Third, I'll introduce custom attributes, afeaturethat 
parallels its .NET counterpart and let's you extend the RTTI information gener- 
ated by the compi ler. Only in the last part of the chapter will I try to get back at 
the reasons behind the extended RTTI and look at practical examples of its use. 



Extended RTTI 

The compiler in Delphi 2010 generates by default much more extended RTTI 
i nformation than any past version. Run ti me i nformation i nd udes al I types, 
i ncl udi ng cl asses and al I other user def i ned types as wel I as the core data types 
predefined by the compi ler and covers published fields as well as public ones, 
even protected and private elements. This is needed to be able to delve into the 
internal structure of any object. 
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A First Example 

Before we look into the information generated by the compiler and the various 
techniques for accessi ng them, let mejump towards the conclusion and show 
you what can be done using RTTI. The specific example is very minimal and 
could have been written with the older RTTI , but it should give you an idea of 
what I 'm talking about (also considering that not all Delphi developers used the 
traditional RTTI explicitly). 

Suppose you haveaform with abutton, I ike in the Rtti Intro example. You can 
write the fol lowi ng code to read the val ue of the control 's C a p t i on property: 

uses 

Rtti; 

procedure TF or mRt t i I nt r o. bt nl nf oCI i c k ( Sende r : TObject); 
va r 

context: T R 1 1 i Context; 
begi n 

Log (context. 

Get Type( TBut t on) . 

Get Pr oper t y( ' Capti on 1 ) . 

GetVal ue( Sender) . ToSt ri ng) ; 

end; 

The code uses the TRtti Context record to refer to i nformati on about the 
T B u 1 1 o n type, from this type information to the RTTI data about a property, 
and this property data is used to refer to the actual val ue of the property, which 
is converted into a string. If you are wondering how this works, keep reading. 
M y poi nt here is that this approach can now be used not only to access a prop- 
erty dynamically, but also to read the values of fields, including private fields. 

We can al so change the val ue of a property, as the second button of the Rtti I n- 

tro example shows: 

procedure T F o r mR tti I ntro. btnChangeCI i ck(Sender: TObject); 
va r 

context: TRtti Context; 
aProp: TRtti Property; 
begi n 

aProp := context. GetType(TButton). GetProperty(' Capti on' ); 
a P r o p . S e t Va I u e ( b t nCha ng e , StringOfChar ( 
' random ( 10) + 1) ) ; 

end; 

This code repl aces theCa pt i on with a random number of * s . Thedifference 
from the code above is that it has a temporary local vari able referri ng to the 
RTTI i nformati on for the property. Now that you have an idea what we are i nto. 
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let's start from the beginning by checki ng the extended RTTI information gen- 
erated bythecompiler in Delphi 2010. 



Compiler Generated Information 

There is nothing you have to do to let the compiler add this extra information to 
your executable program (whatever its kind: application, library, package...). 
J ustopen a project and compile it. By default, the compiler generates Extended 
RTTI for all fields (including private ones) and for public and published meth- 
ods and properties. You might be surprised by the fact that you get RTTI 
information for private fields, but this is required for dynamic operations like 
binary object serialization and tracing objects on the heap. 

You can control the Extended RTTI generation according to a matrix of set- 
tings: On one axis you have the visibility and on the other the kind of member. 
The fol lowi ng table depicts the default: 

Field Method Property 

Private x 
Protected x 

Public xxx 

Published xxx 

Techn i cal I y, the four vi si bi I i ty setti ngs are i ndi cated by usi ng the fol I owi ng set 
type, declared in the System unit: 

I type 

TVi si bi I i tyCI asses = set of (vcPrivate, 
v c P r o t e c t ed , vcPublic, vcPubl i shed) ; 

There are some ready to use constant values for this set i ndicati ng the default 
RTTI vi si bi I i ty setti ngs applied to T Ob j ect and inherited by all other classes by 
default: 

const 

Defaul tMethodRtti Vi si bi I i ty = [vcPublic, vcPubl i shed] ; 
Defaul tFi el dRtti Vi si bi I i ty = [vcPri vate. . vcPubl i shed] ; 
Defaul tPropertyRtti Vi si bi I i ty = [vcPublic, v c P u b I i s h e d ] ; 

The information produced bythecompiler is control led by a new directive, 
$ RTT I , which has a status i ndicati ng if the setti ng is for the given type or also 
for its descendants (EXPLI CI T or I NHERI TED) fol lowed by three specifiers to 
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set the visibility for methods, fields, and properties. The default applied in the 
System unit is: 

{$RTTI INHERIT 
ME J HODS ( Defaul t Met hodRt t i Vi si bi 1 1 t y) 
Fl ELDS( Defeul tFi el dRtti Vi si bi 1 1 ty) 
PROPERTI ES( Defaul tPropertyRtti Vi si bi 1 1 ty) } 

To completely disablethe generation of extended RTTI for all of the members 
of your classes you can use the following directive 17 : 

{$RTTI EXPLI CI T METHODS! [ 1 ) FIELDS(U) PROPERTI ES( [}} } 
When using this setting, consider it will be applied onlyto your code and a 
complete removal is not possi ble, as the RTTI i nformation for the RTL and VCL 
classes is already compiled into the corresponding DCUs and packages. Keep 
alsoin mind thatthe$ RTTI directivedoesn'tcauseanychangeonthetradi- 
tional RTTI generated for published types: This is still produced regardless of 
the $ RTTI directive 13 . 

What you can do with this directive is avoid the Extended RTTI being gener- 
ated for your own classes. At the opposite end of the scale, you can also increase 
the amount of RTTI bei ng generated, i ncl udi ng private and protected methods 
and properties, if you wish (although it doesn't make a lot of sense). 

Larger Executable Files 

The obvious effect of adding Extended RTTI information to an executable file is 
that the file will grow larger (which has the main drawback of a larger file to 
distribute, as the extra loading time and memory footprint would be almost 
unnoticeable). For very small programs, the effect is somewhat minimal, but in 
large applications the increase will be significant. I'll look at very small pro- 
grams fi rst, testi ng two appl i cations I 've used over the years and with multiple 
versions of Delphi, to see how their size changes. After that, we'll look at a more 
real-world situation. 



17 You cannot place the RTTI directive before the unit declaration, as it happens for other 
compiler directives, because it depends on settings defined in the System unit. If you do 
so, you'll receive an internal error message, which is not particularly intuitive. In any 
case, just move it after the unit statement. 

18 ThenewRTTI processing classes, available in the Rtti unit covered in thecoming section, 
hook to the traditional RTTI and itsPTypel nf o structure. 
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The M i niSize program is not an attempt to bui Id the smal lest possi ble program, 
but rather to bui Id a very smal I program that does somethi ng: it reports the size 
of its own executable file. This programs doesn't use the VCL and only a very 
minimal portion of the RTL. All of the example code is as follows: 
program Mi ni Size; 

uses 

Wi ndows ; 

{$R *. RES} 
va r 

nSize: Integer; 
h F i I e: THandl e; 
strSize: String; 

begi n 

// open the current file and read the size 
h F i I e : = CreateFi I e ( PChar ( ParamStr ( 0) ) , 

0, Fl LESHAREREAD, nil, OPENEXI STI NG, 0, 0); 
nSi ze : = Get Fi I eSi ze ( h F i I e , nil); 
CI oseHandl e ( h F i I e ) ; 

// copy the size to a string and show it 
S e t L e n g t h ( s t r S i z e , 2 0); 
Str (nSize, strSize); 

MessageBox (0, PChar (strSize), 'Mini Program', MB_ OK ) ; 
end. 

The program opens its own executable fi le after retrievi ng its name from the 
fi rst command- 1 i ne parameter (P a r a mS t r ( 0 ) ), extracts the size, converts it 
into a string using the old-fashioned St r function, and shows the result in a 
message. The program uses the S t r function for the i nteger-to-stri ng conver- 
sion to avoid including the SysUti Is unit, which defines all of the more complex 
formatting routines and would impose a little extra overhead. The foil owing list 
compares past versions with Delphi 2010: 

• Delphi 5 compiled this program to 18,432 bytes 

• Delphi 6 reduced it to 15,360 bytes 

• Delphi 7 produced afileof 15,872 bytes 

• Delphi 2005 made a slightly bigger file at 16,384 bytes 

. Both Delphi 2006 and Delphi 2007 make it grow to 19,456 bytes 

• I n Delphi 2009 the program size was 20,992 bytes. 
. I n Delphi 2010, it grows to 29,184 bytes. 

The size difference (due to the RTTI for the compiler types and those defined in 
the System and Windows units) is quite relevant for a do-nothing program. 
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Now let's move one step ahead, and I 'II recompile another programs I used in 
past books. This is called Mini Pack and demonstrates a complete application, 
with its own main form, displaying the size of its executable in the caption. The 
name comes from thefact I compilethis program with runtime packages, 
obtai ni ng the fol lowi ng executable sizes: 

• 17,408 bytes in Delphi 7 

• 16,384 bytes i n Del phi 2005 

. 15,872 bytes i n Del phi 2006 and 2007 

• 16,384 bytes i n Del phi 2009 
. 17,920 bytes in Delphi 2010 

This is certai nly quite good, however it tells us very I ittle about the effect of dis- 
tributing afull blown application, using multiple units and built without 
runtime packages. 

As a further example i n the ExeSizeTest folder I 've taken an existi ng program I 
wrotein Delphi 2009 for showing a CI ientDataSet with Unicode strings. By 
using the CI ientDataSet component and a DBGrid control, the program pulls in 
afair amount of the VCL and RTL, including the database portion. 

The i ncrease i n size for such a program is very significant: 

. In Delphi 2009 it compiles to 1,025,024 bytes (about 1MB) 
. In Delphi 2010 it takes 1,552,384 bytes (a I ittle over 15MB) 

If you are distributing internal applications, it won't bea big deal, but if your 
program is distributed in large numbers over the I nternet, possibly with fre- 
quent updates, this increase might affect you in a significant way. 

What can be done to reduce it? Cutting off Extended RTTI will decrease the 
size of your compiled program, but won't affect the library files. Inthe specific 
example (which has a single form with limited code, so it is not very significant) 
adding the $ RTTI directive shown earlier will trim only 1Kb from the execut- 
able, down to 1,551,360. 

Weak and Strong Types Linking 

What else could you do to reduce the size of the program, other then resorting 
to using Run Time Packages? There is actually something you can do, even if its 
effect won't be big, it will be noticeable. 
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When eval uati ng the RTTI information available in the executable file, consider 
that what the compiler adds, thelinker might remove. By default, classes and 
method not compiled in the program will not get the Extended RTTI (which 
would be quite useless), as they don't get the basic RTTI either. At the opposite, 
if you want all Extended RTTI to be included and working, you need to link in 
even classes and methods you don't explicitly refer to in your code. 

There are two new compi ler setti ngs you can use to control the i nformation 
being linked into the executable. Thefirst, which is fully documented, isthe 
$ We a k L i n k RT T I directive. By turning it on, for types not used in theprogram, 
both the type itself and its RTTI i nformation wi 1 1 be removed from the fi nal 
executable. The previous program, even without the$ RTTI directive, is 
reduced down to 1,414,144. 

At the opposite, you can force the i ncl udi ng of al I type and thei r Extended RTTI 
usi ng the undocumented $St rongLi nkTypes di recti ve. The effect on the pro- 
gram is dramatic, with almost a two fold increase to the already large program 
size, up to 2,807,296. 

The following list summarizes the effect of this linker options on this program: 

. Delphi 2009: 1025,024 bytes 

. Delphi 2010 (default settings) 1,552,384 bytes 

. Delphi 2010 (with $WeakLi n k RTT I ) 1,414,144 bytes 

. Delphi 2010 (with $ St rongLi nkTypes ) 2,807,296 bytes 



The Rtti Unit 

If the generation of extended RTTI for all types is the first pi liar for the new 
RTTI of Delphi 2010, the second pillar is the ability to navigate this information 
in a much easier and higher level way, thanks to the new Rtti unit. The third 
pillar, as we'll see, is the support for custom attributes. But let me proceed one 
step at a time. 

Traditionally, Delphi applications could (and still can) use the functions of the 
Typl nfo unit to access the "published" run time type information. This unit 
defines several low-level data structures and functions (all based on pointers 
and records) with acoupleof higher level routines to make things a littleeasier. 
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The new Rtti unit, i nstead, makes it very easy to work with the extended RTTI , 

providi ng a set of classes with proper methods and properties. To access the 

various objects, the entry point istheTRt t i Context record structure, which 

has four methods to look for the avail able types: 

function GetType (ATypelnfo: Pointer): TRtti Type; overload; 

function GetType ( A C I ass: TCIass): TRtti Type; overload; 

function GetTypes: TAr r a y <T Rt t i Type>; 

function FindType (const AQual i f i edName: string): TRtti Type; 

As you can see you can pass a class, a P T y p e I n f o poi nter obtai ned from a type, 
a qualified name (the name of the type decorated with the unit name, as in 
"System.TObj ect") , or retri eve the enti re I i st of types, def i ned as an array of Rtti 
types: TAr r ay<TRt t i Type> 19 . 

Thi s I ast cal I i s what I 've done i n the fol I owi ng I i sti ng, part of the TypesL i st 
example: 

procedure TFormTypesLi st, btnTypesLi stCI i ck( Sender: T Object); 
va r 

aCont ext : TRtti Context; 
theTypes: TAr ray<TRt t i Type>; 
aType: TRtt i Type; 
begi n 

Li stBoxl. CI ear; 

theTypes := a Co n t ex t . Ge t Ty pe s ; 
f or aType i n t heTypes do 
i f aType. I s I nst ance then 

Li stBoxl. I terns. Ad d ( aType. Qual i fi edName) ; 
Li stBoxl. Sorted : = True; 
end; 

TheGet Types method returns the complete list of datatypes, but the program 
filters only the types representing classes (instances in the jargon used by the 
Rtti unit). There are about a dozen other classes representing types in the unit. 

The individual objects in the types list are of classes which inherit from the 

TRtti Type base class. Specifically, we can look for theTRt ti I nst anceType 

class type, as in the fol lowing modified snippet: 

for aType in theTypes do 

if aType is T Rt t i I nst anceType then 

Li stBoxl. I terns. Ad d ( aType. Qual i fi edName) ; 



19 Thenotation used here is the instantiation of a generic class, in this case a generic dy- 
namic array. Generics were introduced in Delphi 2009 and are used significantly in the 
Rtti unit, as we'll see in some examples. The topic is too complex to introduce in a foot- 
note, so all I can doisrefer you to the specific chapter on generics in my "Delphi 2009 
Handbook". 
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I n the fol I owi ng list you can see the enti re i nheri tance graph for the cl asses that 

derivefromtheabstractTRt t i Obj ect cl ass and are defined in the Rtti unit: 

TRtti Obj ect (abstract) 
TRt t i Na medObj ect 
TRtti Type 

TRtti StructuredType (abstract) 
TRtti RecordType 
TRt t i I nst anceType 
TRtti I nterfacetype 
TRt t i Or di na I Type 

TRtti Enumerati onType 



TRt t 
TRt t 
TRt t 
TRtt 
TRt t 



I nt 6 4 T y p e 
Met hodType 
Cl assRefType 
Set Type 
St r i ngTy pe 



TRtti An si Stri ngType 
TRt t i Fl oatType 
TRtti ArrayType 
TRtti Dynami cArrayType 
TRt t i Poi nt erType 
TRtti ProcedureType 
TRtti Me mb e r 
TRt t i Fi el d 
TRt t i Property 

TRtti I nstanceProperty 
TRt t i Met hod 
TRt t i Pa r a me t e r 
TRtti Package 
TRt t i ManagedFi el d 

Each of these classes provides specific i nformation about the given type. As an 
example, only aTRt t i I nterf aceType offers a way to access to the interface 
GUID. Notice, on the other hand, that there is no Rtti obj ect to access indexed 
properties (liketheSt r i n g s [ ] ofaTStringList). 



Rtti Objects Lifetime Management and the 
TRttiContext record 

I f you look at the source code of the bt nTypesLi stCI i ck method I isted 
earlier, there is something that looks quite wrong. TheGet Ty pes call returns 
an array of types, but the code doesn't free these internal objects. The reason is 
that theT Rtti Context record structure becomes the effective of owner for al I 
of the Rtti objects that are bei ng created. When the record is disposed (that is, 
when it goes out of scope), an i nternal i nterface is cleared i nvoki ng its own 
destructor that clears all oftheRtti objects that were created through it. 
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TheTRt t i Context record actually has a dual role. On one side it controls the 
lifetime of theRtti objects (as I just explained), on the other hand it caches Rtti 
i nformation that is quite expensive to recreate with a search. That's why you 
might want to keep reference to theT Rt t i Context record alive for an exten- 
ded period, all owing you to keep accessing the Rtti objects it owns without 
having to recreate them (again, the expensive operation). 

Internally theT Rt t i Cont ext record usesaglobal pool of typeTRt t i Pool , 
which uses a critical section to make its access thread safe 20 . So, to be more pre- 
cise, the Rtti pool is shared among TRtti Context records, so the pooled Rtti 
objects are kept around whi le at least oneT Rtti Context record is i n memory. 
To quote the comment in the unit: 

\{... working with RTTI objects without at least one context being 
alive is an error. Keeping at least one context alive should keep 
the Pool var I abl e val I d. } 

I n other words, you have to avoid caching and keeping Rtti objects around after 

you've released the Rtti context. This is an example that leads to an memory 

access vi ol ati on ( agai n part of the TypesL i st exampl e) : 

function GetThi sType (aClass: TCIass): TRtti Type; 
var 

aCont ext : TRtti Context; 
begi n 

Result := a Co n t ex t . Ge t Ty p e ( a CI a s s ) ; 
end; 

procedure TFormTypesLi st. ButtonlCI i ck(Sender: T Object); 
var 

aType: TRtt i Type; 
begi n 

aType : = GetThi sType ( TFor m) ; 
ShowMessage (aType. QualifiedNa me); 
end; 

To summarize, the Rtti objects are managed by the context and you should not 
keep them around. The context in turn is a record, so it is disposed of automat- 
ically. You might seecodethat uses theT Rt t i Context in the foil owing way: 

context := TRtti Context. Create; 
try 

// use the context 
finally 

context. Free; 
end; 



20 There are exceptions to the thread-safety of theRtti pooling mechanism, described in 
some detail in the comments available in the Rtti unit itself. 



Marco Cantu, Delphi 2010 Handbook 



74 - Chapter 3: Extended RTTI and Attributes 



The pseudo-constructor and pseudo-destructor set the internal interface, that 

manages the actual data structures used behi nd the scenes, to n i I cleani ng up 

the pooling mechanism. However, as this operation is automatic for a local type 

such as a record, this is not needed, unless somewhere you refer to the context 

record using a pointer. For more information about the internals of the 

TRtti Context record you can refer to the fol I owi ng bl og post by Berry Kelly: 

http://blog.barrkel.com/2010/01/ 

delphi-2010-rtti-contexts-how-they-work.html 



A Tree of Classes (and Class I nformation) 

The most relevant types you might want to inspect at run time are certainly the 
so-called structured types, that is instances, interfaces, and records. Focusing 
on instances, we can refer to the relationship among classes, by fol I owing the 
BaseType information avail able for instance types. 

This is what I 'vedone in theTypeList example, which can build a tree of the 

classes in a TreeView control, using the fol I owing recursive method: 

function TFormTypesList.AddTypeToTree ( 

atype: TRtt i Type) : TTreeNode; 
va r 

Parent Node: TTr eeNode; 
begi n 

// already there? 

Result := GetNodeFromTree (atype. na me); 

if Resul t = ni I t hen 
begi n 

if atype. BaseType = ni I then 

// add root node 

Parent Node : = ni I 
else 

// add the base class if not there 
ParentNode := AddTy peToT r e e ( atype. BaseType) ; 
// now add the child class 

Result := TreeVi ewl. I terns. AddChi I d (ParentNode, atype. Name); 
end; 
end; 

At the beginning the method uses the Get NodeFromTree function to check if a 
type with the given nameisal ready present in the tree, eventually returning the 
correspondi ng node. The next step is to look for or add the base class type to 
the tree, so that at the end the method can add the current node as a sub- node 
(or using nil as base node if it has no based ass, as happens for T Ob j ect ). 
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This Ad dTypeToTr ee method is i nvoked for each type representi ng an 
instance, with a loop similar to that we have already seen. Notice that we could 
have added some type i nformati on to each tree node, but i n doi ng so we woul d 
have risked keeping the reference to these Rtti objects around after the context 
and the corresponding pooling mechanism would have deleted them. As an 
example, we can see the type of the demo form in this portion of the types tree: 



■ System. TObject 
J ■ Classes ."Persistent 

Classes .TComponent 
J Controls.TControl 

■ Controls .TVVinContro I 
J - Forms .TScrollingWinControl 
Forms.TCustomForm 
J ■ Forms.TFornn 

■ TypelnfoForrn.TFormTvpelnfo 

■ TypesUstMainForm.TForrnTy pes List 
■■ Forms TCustomDockPorrn 

■ ComCtrls.TCustomHeaderControl 

; - Com Ctrls.THeader Control 
ComCtrls .TCustomTTeeVie'A 1 

Com Ctrls.TTree View 
Controls, TC us torn Control 
■ Control s. THintVVindow 
■■ Control s.TCustomPanning Window 



□ 



Accessi ng types is certai nly an i nteresti ng starti ng poi nt, but what is relevant 
and specifically new is the ability to learn about further details of these types, 
including their members. As you click on one of the types (heretheTTi mer 
class) the program displays a list of properties, methods, and fields of the type: 



jjj^ Form Type Info - ExtCtrls.TTsmer 






[ = 1 must*!' 


Properties 


Methods 




Fields 


iEnabled: Boolean [pbTj 


Create [pub] 




FInterval: Cardinal [pri] 


Interval: Cardinal [pbl] 


Destroy [pub] 




FWindowHandle: HWND [pri] 


OnTimer: TNotify Event [pbl] 


Create [pub] 




FOnTimer: TT-Jofjf|/Event [pri] 


CornObject: Ilnterface [pub] 


Destroy [pub] 




FEnabled: Boolean [pri] 


ComponentCount: Integer [pub] 


Before Destruction [pub] 




FOwner: TComponent [pri] 


Componentlndex: Integer [pub] 


DestroyComponents [pub] 




FName: TComponentf-'Jarne [pri] 


ComponentState: TComponentState [pu 


Destroying [pub] 




FTag: Integer [pri] 


ComponentStyle: TCornponentStyle [pub 


Execute Action [pub] 




FComponents: TList [pri] 


Designlnfo: Integer [pub] 


FindCornponent [pub] 




FFreeNotifies: TList [pri] 


Owner: TComponent [pub] 


FreeNotifi cation [pub] 




FDesignlnfo: Integer [pri] 


VCLComObject: Pointer [pub] 


RemoveFreeNotification [pub] 




FComponentState: TComponentState [p 


Name: TComponentName [pbl] 


FreeOnRelease [pub] 




FVCLComObject: Pointer [pri] 


Tag: Integer [pbl] 


Gerfnurmerator [pub] 




FComponentStyle: TComponentStyle [pr 




GetParentCornponent [pub] 




FSortedComponents: TList [pri] 




GetNamePath [pub] 








HasParent [pub] 








InsertComponent [pub] 








RemoveComponent [pub] 








SetSubComponent [pub] 








SateCa II Exception [pub] 








UpdateAction [pub] 








Is I m pie mentor Of [pub] 







Marco Cantu, Delphi 2010 Handbook 



76 - Chapter 3: Extended RTTI and Attributes 



The unit of this secondary form, which can probably be adapted and expanded 

to be used as a generic type browser in other applications, has a method called 

ShowTypel nformati on that walks through each property, method, and field of 

the given type, adding them to three separate list boxes with theindication of 

their visibility (pri for private, pro for protected, pub for public, and pbl for 

published, as returned bytheVi s i bi I i t yToken function): 

procedure ShowTypel nformati on (aType: TRtti Type) ; 
va r 

FormTypelnfo: TFormTypelnfo; 
aProperty: TRtti Property; 
aMethod: TRtti Method; 
a F i el d : TRtti F i el d ; 
begi n 

FormTypelnfo := TFormTypelnfo.Create(nil); 
try 

For mTypelnfo. Caption : = For mTypelnfo. Caption + 

' - ' + aType. Qual i fi edName; 
for aProperty in at ype. Get Pr oper t i es do 

FormTypel nfo. Li stProperti es. I tems. Add ( a P r o p e r t y . Na me + 
': ' + aProperty. PropertyType. Name + ' ' + 
Vi si bi I i tyToken (aProperty. Visibility)); 
for aMethod in at ype. Get Met hods do 

For mTypelnfo, List Methods. Items. Add (aMethod. Name + ' ' + 
Vi si bi I i tyToken (a Me thod, Visibility)); 
for a F i el d in aType. GetFi el ds do 

For mT ypel nfo. Li stFi el ds. I tems. Add ( a F i el d . N a me + ': ' + 
aFi el d. Fi el dType. Na me + ' ' + 
Vi si bi I i tyToken (aFi el d . Visibility)); 
For mT ypel nfo. S h o wMo da I ; 
finally 

For mT ypel nfo. Free; 
end; 
end; 

You could go ahead and extract further i nformati on from the types of these 
properties, get parameter I ists of the methods and check the return type, and 
more. H ere I don't want to bui Id a complete RTTI browser but only give you a 
feeling of what can be achieved. 



RTTI for Packages 

Besi de the methods you can use to access a type or the I i st of types, the record 
TRtti Context has another very i nteresti ng method, Get Pa c kages , which 
returns a list of the run-ti me packages used by the current appl i cation. I f you 
execute this method in an application compiled with no run time packages, all 
you get is the executable file itself. But if you executeit in an application corn- 
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piled with run time packages, you'll get a list of those packages. From that 
poi nt, you can del ve i nto the types made avai I abl e by each of the packages. 
Notice that in this case the types list is much larger, as RTL and VCL types not 
used by the application are not removed by the smart linker. 

I n the TypesL i st appl i cation, clicking on the bt n T y p e s Li st button you'll get 
the I ist of i nstance types i n the I ist box, and also the total number of types i n the 
status bar. When the program iscompiled statically, you'll get 300 instance 
types, while if you turn on run ti me packages that numbers becomes 800. Still, 
this is not the complete I ist of al I classes avai I able i n the Del phi I ibraries, as 
you'll generally not include every avai I able package, but only a limited set. 

If you use run time packages, you can also retrieve the list of units for each of 

the packages ( and the executabl e f i I e) , by usi ng code I i ke: 

procedure TFormTypesLi st. btnPackagesCI i ckfSender: TObj ect) ; 
va r 

aCont ext : TRtti Context; 
aPackage: TRtti Package; 
aType: TRtt i Type; 
begi n 

Li s t Box 1 . CI ear; 

Li stBoxl. Sorted : = False; 

for aPackage in aCon t ext . Get Pa c kages do 

begi n 

Li stBoxl. I terns. Ad d ( 'PACKAGE 1 + a Pa c k a g e . Na me ) ; 
for aType in a Pa c k a g e . Ge t Ty p es do 

i f aType. I s I nst ance then 

begi n 

L i s t Box 1 . I t e ms . Ad d ( ' - ' + aType. Qual i fi edName) ; 
end; 

end; 
end; 

With this code you'll get the list of instance types for each package, starting 
with the executable, as you can see in the following image. 

' & TypesList 1 ■=■ I ^ Iw^J 



PACKAGE C:IJJsersV l 1an:o l ipoajments\RAD Studio^rcijects\weaver^3\TypesList\TypeE * 
-TypelnfoForm.TFormTypelnfo 

- TypesListMainForrn .TFormTypesList 
PACKAGE C:\Windowslpystem32\vd 140. bpl 

-DirectZD , EDirectZDException 

- DirectZD .TDirectZDGraphicsObject 

- DirectZD .TDirectZDBrush 
■ DirectZD .TDirectZDPen 

- DirectZD .TDirectZDFont 

- DirectZD .TDirectZDCanvas 

-DirectZD.TEnumerator<DirectZD.TDirectZDGraphicsObject> 
-DirectZD,TEnumerable<DirertZD.TDirectZDGraphicsObject> 
-Direct2D,TList<Direct2D.TDirect2DGraphicsObject>,TEnumerator 

- DirectZD.TList<DirectZD.TDirectZDGraphicsObject> r 



btnTypesList 



| btnPackages J 



btnMemory 
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The TValue Structure 

The new extended RTTI not only lets you browse the internal structureof a 
program but it also provides specific information, including property and field 
values. Whilethe Typlnfo unit provided theGet PropVal ue function to access 
a generic property and retrieve a variant type with its value, the new Rtti unit 
uses a different structure for holding an untyped element, theTVa I u e record. 

This record can store al most any possi ble Del phi data type and does so by keep- 
i ng track of the origi nal data representation, by holdi ng both a data and a 
format. What it can do is read and write data in the given format. What it can- 
not do is convert from one format to another. So even if a T V a I u e has an 
AsStri ng andanAsI nteger method, you can usetheformer only if thedata 
is representing is indeed a string, the second only if you originally assigned an 
integer to it. For example, in thiscaseyou can usetheAs I nteger method and 
if you call the I s Or d i nal method it will return True: 
va r 

v 1 : TValue; 
begi n 

vl : = 100; 

if vl. I sOrdi nal t hen 

Log (IntToStr (vl. As Integer)); 

However, you cannot usetheAs St ring method, which would raise an invalid 
typecast exception: 
va r 

vl: TValue; 
begi n 

vl : = 100; 

Log (vl, As String); 

Ifyou need a string representation, though, you can usetheToSt r i ng method, 
which has a largec a s e statement trying to accommodate most data types: 
va r 

v 1 : TValue; 
begi n 

vl : = 100; 

Log ( vl. ToSt r I ng) ; 

You can probably get a better understandi ng, by readi ng the words of Barry 
Kelly, Delphi R&D member who worked on RTTI for the Del phi 2010 compiler: 

TValue is the type used to marshal values to and from RTTI-based 
calls to methods, and reads and writes of fields and properties. 
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It's somewhat I ike Variant but far more tuned to the Delphi type sys- 
tem; for example, instances can be stored directly, as well assets, 
class references, etc. It's also morestrictly typed, and doesn't do (for 
example) silent string to number conversions. 

Now that you better understand its role, let's look at the actual capabilities of 
theT V a I u e record. 1 1 has a set of higher level methods for assigni ng and 
extracti ng the actual values, plus a set of low- level pointer based ones. I'll con- 
centrate on the first group. 

For assigning values, TVa I ue defi nes several I mpl i ci t operators, all owing you 

to perform a direct assignment as in the code snippets above: 

citfconst Value: string): TValue; 

c i t ( Value: Integer): TValue; 

c i t ( V a I u e : Extended): TVal ue; 

ci t ( V a I ue: I n 1 6 4 ) : TVal ue; 

ci t ( V a I ue: TObj ect) : TVal ue; 

ci t ( Va I ue: TCI ass) : TVal ue; 

c i t ( Value: Boolean): TValue; 

What all these operators do is call theF r o m generic class method: 
class function F r o m<T >( const Value: T) : TValue; static; 

When you cal I these class functions you need to specify the data type and also 
pass a val ue of that type, I i ke the fol lowi ng code repl aci ng the assi gnment of the 
value 100 of the previous code snippets: 

| vl := TVal ue. Fro m<l nteger>( 100) ; 

This is a sort of universal technique for movi ng any data type into a T V a I u e . 

Once the data has been assigned, you can use several methods to test its type: 

Kind: TTypeKi nd read Get Ty pe Ki nd ; 
sObj ect : Bool ean; 



c 


ass 


operator 


1 mp 


c 


a s s 


operator 


1 mp 


c 


a s s 


operator 
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c 


a s s 


operator 


1 mp 


c 


a s s 


operator 


1 mp 


c 


a s s 


operator 


1 mp 


c 


a s s 


operator 


1 mp 



property 
f unct i on 
fundi on 
f unct i on 
fundi on 
fundi on 



sClass: Boolean; 
sOrdinal: Boolean; 
s Ty p e <T >: Bool ean; 
s Array: Boolean; 



over I oad ; 



Notice that the generic I s Ty pe can be used for almost any data type. 

There are correspondi ng method for extracti ng the data, but agai n you can use 
only the method compatible with the actual data stored in theT Val ue,asno 
conversion is taking place: 



f unct i on 
fundi on 
fundi on 
fundi on 
fundi on 



AsObj ect 
As CI ass: 
As Or di na I 
AsType<T> 
As I nt eger 



TObj ect; 
TCI ass; 
I nt 64; 
T; 

I nt eger 
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fund 


on 


fund 


on 


fund 


o n 


fund 


on 


fund 


on 


fund 


on 


fund 


on 



As Boolean: Boolean; 
As Extended: Extended; 
As I nt 64: I nt 64; 
As Interface: llnterface; 
As String: string; 
As Va r i a n t : Variant; 
As Currency: Currency; 

Some of these methods double with a Try version that returns False, rather 

than raising an exception, in case of an incompatible data type. There are also 

some limited conversion methods, the most relevant of which are the generic 

Cast andtheToStri ng function I 'veal ready used in the code: 

function Cast <T >: TValue; overload; 
function ToString: string; 



Reading a Property with TValue 

The i mportance of T V a I ue lies in the fact that this is the structure used when 

accessing properties and field values using the extended RTTI andtheRtti unit 

in Delphi 2010. As an actual exampleof the use of TVa I ue, we can use this 

record type to access both a published property and a private field ofaTButton 

object, as in the following code (part of the Rtti Access demo): 

procedure TForm3 9. btnReadVal uesCI i ck( Sender: TObject); 
va r 

context: TRtti Context; 
aType: TRttiType; 
aProperty: TRtti Property; 
a Va I u e : TValue; 
a F i el d : TRtti F i el d ; 
begi n 

aType := c o n t ex t . Ge t Ty pe ( T Bu t t o n ) ; 
aProperty := aTy pe . Ge t P r o pe r t y ( ' Capt i on ' ) ; 
aValue := a P r o pe r t y . Ge t Va I ue ( S e n de r ) ; 
ShowMessage (aVal ue.AsStri ng); 

aField := aType. GetFi el d ( 'FDesignlnfo') ; 
aValue := a F i e I d . Ge t Va I ue ( Se nd e r ) ; 
ShowMessage (IntToStr ( a Va I u e . As I n t e ge r ) ) ; 
end; 



I nvoking Methods 

Not only does the new extended RTTI lets you access values and fields, but it 
also provides a simplified way for calling methods. In this case you have to 



Marco Cantu, Delphi 2010 Handbook 



Chapter 3: Extended RTTI and Attributes - 81 



defi ne a T V a I u e element for each parameter of the method. There is a global 

I n v o k e function which you can call for executing a method: 

function I nvoke(Code Address: Pointer; const Args: TAr r a y <T Va I u e >; 
Ca I I i ng Co n v e n t i o n : TCallConv; AResul tType: PTypelnfo): TValue; 

As a better alternative, there is a simplified I n v o k e overloaded method in the 

TRtti Method class: 

function I nvoke( I nstance: TObject; 

const Args: array of TValue): TValue; overload; 

An example of invoking a method using this second simplified form is part of 

the Rtti Access demo and listed below: 

procedure TForm3 9. btnl nvokeCI i ck( Sender: TObject); 
va r 

context: TRt t i Context; 
aType: TRttiType; 
aMethod: TRtti Method; 
the Values: array of TValue; 
begi n 

aType := c o n t ex t . Ge t Ty pe ( T Bu t t o n ) ; 
aMethod := aType. Get Met hod( ' FlipChi Idren' ) ; 
Set Length ( t heVal ues, 1) ; 
t heVal ues[ 0] : = True; 
aMethod. I nvoke(sel f, theValues); 
end; 



Low- Level TValue 



TheT V a I u e structure i nd udes a few hel pers that make it easy to assign or 
extract val ues of various data types to or from it. I n some situations, however, it 
isnicetobeabletocopytherawbytesoftheTVal ue data into a specific data 
structure. This can be done using the Ma ke and Get RawDat a methods, as i n the 
followi ng sni ppet that saves an i nteger val ue i nside a (newly created) T V a I u e 
record: 
va r 

a Va I u e : TValue; 
int Value: Integer; 
begi n 

i nt Val ue : = 100; 

T Va I u e . Ma ke ( i n t Va I u e , Typel nf o( I nt eger ) , aValue); 

Of course, this is not needed as I could have used a higher level approach. At 
times, though, you won't have the alternative or, in some cases, the higher level 
approach would be more complicated than the low-level code. 
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As an example, consider the method (part of theRtti Access application, I ike the 
code sni ppet above) , used to read the val ue of a set property, the A n c h o r 5 
property of a button. TheT 0 S t r i n g method of theT V a I u e record lets you dis- 
play a readable output, but if you need to read the actual numerical value (in 
thiscaseaBy t e ) you can write the two lines at the end: 
va r 

context: TRtti Context; 
aType: TRtt i Type; 
aSetType: TRt t i SetType; 
aProperty: TRtti Property; 
aVal ue: TVal ue; 
b: Byte; 
begi n 

aType := c 0 n t ex t . Ge t Ty pe ( T Bu t t 0 n ) ; 
aProperty := a T y pe . Ge t P r 0 p e r t y ( ' Anchors ' ) ; 
aSetType := a P r 0 p e r t y . P r 0 p e r t y Ty pe . As S e t ; 
Log ('Type: ' + aSetType. ToString); 

aValue := aProperty.GetVal ue(Sender); 
Log ('Anchors: ' + aValue. ToString); 

// extract numerical value 
a Val ue. Extract Ra wDa t a ( @b ) ; 
Log (' Anchors: ' + IntToStr ( b ) ) ; 
end; 

The output of this method is: 

Type: TAnchors 
[Anchors: [akLeft, akTop] 
Anchors: 3 

In most cases the higher level approach would work, but in specific circum- 
stances it si mply won't. Tryi ng to get the numerical val ue of the set by usi ng the 
GetOrdi n a I method of T V a I u e , for example, will raise an exception because 
the set i s not an ordi nal val ue. I f you want to ski p si mi I ar exceptions and j ust 
read (or write) the data, you'll need to use the low- level calls. 



Custom Attributes 



The f i rst part of this chapter gave you a good grasp of the extended RTTI gener- 
ated by the Del phi 2010 compiler and of the RTTI access capabilities 
introduced bythenewRtti unit. In the second part of the chapter we can finally 
focus on one of the key reasons this enti re architecture was i ntroduced: the 
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possibility to defi ne custom attributes and extend the compiler-generated RTTI 
in specific ways. We'll look at this technology from a rather abstract perspect- 
ive, and later focus on the reasons this is an i mportant step forward for Del phi , 
by looking at practical examples. 

What is an Attribute? 

An attribute (in Delphi or .NET terms) or an annotation (in J avaj argon) is a 
comment or indication that you can add to your source code, applying itto a 
type, afield, a method, or a property) and the compiler will embed in the pro- 
gram. This is generally indicated with square brackets as in: 

type 
[ My At tribute] 
T My CI ass = class 

By reading this information at design time in a development tool or at run time 
in the final application, a program can change its behavior depending on the 
values it finds. 

General I y attri butes are not used to change the actual core capabi I i ti es of a cl ass 
of objects, but rather to let these classes specify further mechanisms they can 
participate in. Decl ari ng a cl ass as serializable doesn't affect its code in any 
way, but lets the serial ization code know that it can operate on that class and 
how (in case you provide further information along with the attri bute, or fur- 
ther attributes marking the class fields or properties). 

This is exactly how the existing and limited RTTI was used inside Delphi. Prop- 
erties marked as published could show up in the object inspector, be streamed 
to a DFM file, and be accessed at run time. Attributes open up this mechanism 
to become much more flexible and powerful. They are also much more complex 
to use, and easy to misuse, as are any powerful language features. I mean, don't 
throw away al I the good thi ngs you know about Object Oriented Programmi ng 
to embrace this new model, but complement one with the other. 

As an example, an employee class will still be represented in a hierarchy asa 
derived class from a person class; an employee object will still have an I D for 
his or her badge; but you can "mark" or "annotate" the employee class as class 
that can be mapped to a database table or displayed by a specific runtime form. 
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So we have inheritance (is-a), ownership (has-a), and annotations (marked-as) 
as three separate mechanism you can use when designing an application. 

After you've seen the compiler features supporti ng custom attributes in Delphi 
2010 and looked at some practical examples, the abstract idea I just mentioned 
should become more understandable, or at least that's my hope! 



Attribute Classes and Attribute Declarations 



H ow do you def i ne a new attri bute cl ass (or attri bute category) ? You have to 
inherit from the newTCu 5 1 o mA 1 1 r i bute class avail able in the System unit: 
I type 

S i mp I eAttri bute = cl ass( TCusto mA 1 1 r i bute) 
end; 

The cl ass name you give to the attri bute cl ass wi 1 1 become the symbol to use i n 
the source code, with the optional exclusion of the Attri bute postfix. So if you 
name your class Si mpl eAttri bute you'll be able to use in the code an attrib- 
ute called Si mpl e or Si mpl eAttri bute. Anyway this is the reason the classic 
initial T for Delphi classes isgenerally not used in case of attributes. 

Now that we have defined acustom attribute, we can apply it to most of the 

symbols of our program: types, methods, properties, fields, and parameters. 

The syntax used for applying attributes is the attri bute name within square 

brackets: 

type 
[Si mp I e ] 

TMyCI as s = c I a s s ( TOb j e c t ) 
public 

1 S i mp I e ] 

procedure One; 

In this case I've applied the Si mpl e attri bute to the class as a whole and to a 
method. Beside a name, attri bute can support one or more parameters. The 
parameters passed to an attribute must match those indicated in the con- 
structor of the attri bute cl ass, if any. 
type 

Val ueAttri bute = cl ass ( TCust omAt t r i but e) 
pr i vat e 

F Value: Integer; 
publ i c 

constructor Cr eat e( N: Integer); 
property Value: Integer read FVal ue; 
end; 
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This is how you can apply this attribute with one parameter: 

type 

[ Val ue( 22) ] 

T My CI ass = cl a s s ( T Ob j ect) 
public 

[ Val ue( 0) ] 

procedure Two; 

The attribute values, passed to its constructor, must be constant expressions, as 
they are resolved at compile time. That's why you arelimited to just a few data 
types: ordinal values, strings, sets, and class references. On the positive side, 
you can have multiple overloaded constructors with different parameters. 

Notice you can apply multi pie attri butes to the same symbol, as I 've done i n the 
RttiAttrib example, which summarizes the code snippets of this section: 
type 

[ SI mpl e] [ Val ue( 22) ] 

TMyCI as s = c I a s s ( TObj e c t ) 

public 

[ S I mp I e ] 

procedure One; 

[ Val ue( 0) ] 

procedure Two; 
end; 

What if you try to use an attri bute that is not defi ned (maybe because of a miss- 

i ng uses statement)? U nl ucki ly you get a very misleadi ng warni ng message: 

[DCC Warning] Rtti Attri bMai nForm. pas(44) : W1025 
Unsupported language feature: ' c us t o m a t t r i b u t e ' 

The fact this is a warning implies the attribute will beignored, so you have to 

watch out for those warni ngs or even better treat the "unsupported I anguage 

feature" warni ng I i ke an error (somethi ng you can do i n the H i nts and Warn- 

ings page of the Project Options dialog box): 

[DCC Error] RttiAttri bMai nForm. pas(38) : 

E1025 Unsupported language feature: 1 c us t o m a t t r i b u t e 1 

Finally, compared to other i implementations of the same concept, there is cur- 
rently no way to I i mit the scope of attri butes, I i ke decl ari ng that an attri bute can 
be applied to a type but not to a method. What is available in the editor, 
instead, isfull support for attributes in the rename ref adoring 21 . Not only you 
can change the name of the attri bute class, but the system will pick up when the 
attri bute is used both in its full name and without the final "attribute" portion. 



21 Attri butes refactoring was first mentioned by Malcolm Groves on hisblogat 
http:// www.malcolmgroves.com/ blog/ ?p=554 
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Browsing Attributes 

N ow th i s code wou I d seems total I y usel ess i f there wasn 't a way to d i scover 
which attributes aredefined, and possibly inject a different behavior to an 
object because of these attri butes. Let me start focusi ng on the first part. The 
classes of the Rtti unit let you figure out which symbols have associated attrib- 
utes. This is code, extracted from the Rtti Attri b example shows the list of the 
attri butes for the current cl ass: 

procedure TMyCI ass. One; 
va r 

context: TRtt i Context ; 
attri butes: TArray<TCustomAttri but e > ; 
attri b : TCust omAt t r i but e; 
begi n 

attributes := c o n t e x t . Ge t Ty p e ( CI a s s Ty p e ) . Ge t At t r i b u t e s ; 
for at t r i b in attributes do 
Form3 9. L o g ( attri b.CI assName); 

Running this code will printout: 

Si mpl eAttri bute 
Va I ue At t r i bute 

You can extend it by adding the following code to thef o r - i n loopcodeto 

extract the specif i c val ue of the gi ven attri butes type: 

if at t r i b is Val ueAttri bute then 
F o r m3 9 . L o g ( 1 - 1 + I n t T o S t r 

(Val ueAttri bute(attri b).Val ue)); 

What about fetchi ng the methods with a given attri bute, or with any attri bute? 
You cannot filter the methods up front, but have to go through each of them, 
check their attributes, and see if it is relevant for you. To help in this process, 
I 've written a function that checks if a method supports a given attri bute: 
type 

TCust omAt t r i but eCl ass = class of TCus t o mAt t r i but e ; 

function HasAttri bute ( a Me t hod: TRtti Method; 

attri bClass: TCustomAttributeClass): Boolean; 
va r 

attri butes: TArray<TCustomAttri but e > ; 
attri b: TCust o mAt tribute; 
begi n 

Res ul t : = Fal se; 

attributes := a Me t h od . Ge t At t r i b u t e s ; 
for at t r i b in attributes do 

if at t r i b. I nher i t s Fr om ( at t r i bCI ass ) then 
Exit (True); 

end; 
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TheHas At t r i but e function is called bytheRttiAttr program while checking 
for a given attri bute or any of them: 
va r 

context: TRtti Context; 
aType: TRtt i Type; 
aMethod: TRtti Method; 
begi n 

aType := c o n t ex t . Ge t Ty pe ( T My CI a s s ) ; 

for aMethod in aType. Get Met hods do 

if HasAttri bute (aMethod, S i mp I eAttri bute) then 
Log (aMethod.name); 

for aMethod in aType. Get Met hods do 

if HasAttri bute (aMethod, TCustomAttribute) then 
Log (aMethod.name); 

The effect isto list methods marked with the given attributes, as described by 

further L o g calls I 've omitted from the listing above: 

Methods marked with [Simple] attribute 
One 

Methods marked with any attribute 

One 

Two 

Rather than simply describing attributes, what you generally do is add some 

independent behavior determined by the attributes of a class, rather than its 

actual code. As an example, I can inject a specific behavior in the previous 

code: The goal could be calling all methods of a class marked with a given 

attribute, considering them as parameter I ess methods: 

procedure TForm3 9. btnl nvokelfZeroCI i ck( Sender: TObject); 
va r 

context: TRtti Context; 
aType: TRtt i Type; 
aMethod: TRtti Method; 
aTarget: T My C I ass; 
zeroParams: array of TValue; 
begi n 

aTarget : = T My Class. Create; 
try 

aType := c o n t ex t . Ge t Ty p e ( a Ta r g et . CI a s s Ty pe ) ; 
for aMethod in aType. Get Met hods do 

if HasAttri bute (aMethod, Si mpl eAttri bute) then 
aMethod. I nvoke( aTarget , zeroParams); 
finally 

aTarget. Free; 
end; 
end; 
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What this code snippet does is create an object, grab its type, check for a given 
attribute, and invoke each method that has the S i mp I e attribute. Rather than 
inheriting from a base class, implementing an interface, or writing specific code 
to perform the request, all we have to do to get the new behavior is mark one of 
more methods with agiven attribute. Not that this example makes the use of 
attributes extremely obvious: for some common patterns in using attributes 
and some actual case studies you can refer to the final part of this chapter. 



RTTI Case Studies 

Now that I 've covered the foundations of RTTI and the use of attri butes it is 
worth looking into some real world situations in which using these technique 
will prove useful. Thereare many scenarios in which a more flexibleRTTI and 
the ability to customize it through attributes is relevant, butl have no room for 
a long list of situations. What I 'I I do instead is guide you in the step- by- step 
development of two simple but significant examples. 

The f i rst demo program wi 1 1 showcase the use of attri butes to i dentif y sped f i c 
information within a class. In particular, we want to be able to inspect an object 
of a class that declares to be part of the an architecture and have a description 
and a unique ID referring to the object itself. This might come handy in several 
situations, I ike describing objects stored in a collection (either a generic or tra- 
ditional one). 

The second demo wi II be an example of streami ng, specifi cally streami ng a 
class to an XML file. I 'II start from the classic approach of using the published 
RTTI , move to the new extended RTTI , and fi nal ly show how you can use 
attri butes to customize the code and make it more flexible. 

Attributes for I D and Description 

I f you want to have a couple of methods shared among many objects, the most 
classic approach was to define a base class with virtual methods and inherit the 
vari ous obj ects from the base cl ass, overri d i ng the vi rtual methods. Thi s i s n i ce, 
but poses a lot of restrictions in terms of the classes which can participate in the 
architecture, as you have a fixed base class. 
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Astandard technique to overcome this situation isto use an i nterface rather 
than acommon base class. Multiple classes implementing the interface (but 
with no common ancestor class) can provide an implementation of the inter- 
face methods, whi ch act very si mi I arly to vi rtual methods. 

A totally different style (with both advantages and disadvantages) istheuseof 
attributes to mark participating classes and given methods (or properties). This 
opens up more flexibility, doesn't involve interfaces, but is based on a compar- 
atively slow and error-prone run-time information look up, rather than a 
compile-time resolution. This means I'm not advocating this coding style over 
interfaces as a better approach, only as one that might be worth evaluating and 
i nteresti ng to use i n some ci rcumstances. 

The Description Attribute Class 

For this demo, I've defined an attribute with a setting indicating the element is 
it being applied to. I could have used three different attributes, but prefer to 
avoi d pol I uti ng the attri butes name space. Thi s i s the attri bute cl ass def i n i ti on : 

type 

TDescri pti onAttrKi nd = (dakClass, dakDescri pti on, d a k I d ) ; 

Descri pti onAttri bute = class ( T C u s t o mA 1 1 r i bute) 
pr i vat e 

f Da k : TDescri pti onAttrKi nd; 
publ i c 

constructor Create ( a Da k : TDescri pti onAttrKi nd = dakClass); 
property Kind: TDescri pti onAttrKi nd read f Da k ; 
end; 

Notice the use of the constructor with a default val ue for its only parameter, to 
let you use the attri bute with no parameters. 

The Sample Classes 

Next I wrote two sample classes that use the attri bute. Each class is marked 
with the attri bute and has two methods marked with the same attri bute cus- 
tomized with thedifferent kinds. The first (TPe r s o n ) has the descri pti on 
mapped to theGet Name function and usesitsTObj ect . Get Has hCode method 
to provide a (temporary) I D, re-declari ng the method to apply the attribute to it 
(the method code is simply a call to the i nheri ted version): 

I type 

[ Desc r i pt i on] 
TPerson = class 
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pr i vat e 

FBi rthDate: TDate; 
F N a me : string; 
F Country: string; 

procedure Set Bi r t h Da t e( const Value: TDate); 
procedure Se t Cou nt r y ( cons t Value: string); 
procedure SetNa me (const Value: string); 
public 

[ Des c r i pt i o n (dakDescription)] 
function Get Name: st r i ng; 
[ Desc r i pt i on ( dakl D) ] 
function Get St r i ngCode: Integer; 
publ i shed 

property Name: string read GetName write Set N a me ; 
property Bi rthDate: TDate 

read FBi rthDate write SetBi rthDate; 
property Country: string read FCountry write SetCountry; 
end; 

The second class(TCompany)is even si mpl er as i t has i ts own val ues for the I D 
and the description: 

type 

[ Desc r i pt i on] 
TCompany = class 
pr i vat e 

F N a me : string; 

FCountry: string; 

FID: string; 

procedure SetNa me (const Value: string); 
procedure SetlDfconst Value: string); 
public 

[ Des c r i pt i o n ( d a k De s c r i p t i o n ) ] 
function Get Name: st r i ng; 
[ Desc r i pt i on ( dakl D) ] 
function Get I D: string; 
publ i shed 

property Name: string read GetName write Set N a me ; 
property Country: string read FCountry write FCountry; 
property ID: string read FID write SetID; 
end; 

Even if there are similarities among the two classes they are totally unrelated in 
terms of hierarchy, common interface, or anything like that. What they share is 
the use of the same attri bute. 



The Sample Project and Attributes Navigation 

The shared use of the attri bute is used to display information about objects 
added to a list, declared in the main form of the program as: 

| fObj ectsLi st: TObj ectLi st<TObj ect>; 
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This list iscreated and initialized as the program starts: 

procedure TFormDescrAttr. FormCreate( Sender: TObject); 
va r 

aPerson: TPerson; 
aCompany: TCompany; 
begi n 

fObj ectsLi st := TObj ectLi st<T0bj ect>. Create; 

// add a person 

aPerson : = TPerson. Create; 

a Pe r s o n . Na me : = ' Wi I ey' ; 

aPerson. Country := ' Des er t ' ; 

aPerson. Bi rthDate : = Date - 1000; 

fObj ectsLi st. Add( aPerson) ; 

// add a company 

aCompany := TCompany. Create; 

aCompany. Name := 'ACME Inc.'; 

aCompany. ID : = IntToStr (GetTi ckCount); 

aComp any. Country : = ' Wor I dwi de' ; 

fObj ectsLi st. Ad d ( aCompany) ; 

// add an unrelated object 

fObj ectsLi st. Add(TStri ngLi st. Create) ; 

To display information about the objects ( namely the ID and the description, if 

available) the program uses attributes discovery via RTTI . First, it usesa helper 

function to determine if the class is marked with the specific attribute 22 : 

function TypeHasDescr i pt i on (aType: TRtt i Type) : Boolean; 
va r 

attrib: TCust omAt tribute; 
begi n 

for attrib in aType. Get At t r i but es do 
begi n 

if (attrib is Des c r i p t i on At t r i bu t e ) then 
Exit (True); 

end; 

Result : = Fal se; 
end; 

I f this is the case, the program proceeds by getti ng each attri bute of each meth- 
ods, with a nested loop, and checking if this is the attri bute we are looking for: 

if TypeHasDescr i pt i on (aType) then 
begi n 

for a Me t hod in aType. Get Met hods do 

for attrib in a Me t ho d . Ge t At t r i b u t e s do 
if attrib is Descri pti onAttri bute then 



22 In this case you need to check for the full class name, Descri pti onAttri bute, and 
not only "Description", which isthe symbol you can use when applying the attri bute. 
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At the core of the loop, the methods marked with attri butes are i nvoked to read 

the results in two temporary stri ngs (later added to the user interface): 

if attri b is Descri pti onAttri bute then 
case Descri pti onAttri bute(attri b). Ki nd of 
d a k C I ass: ; // ignore 
dak De s c r i pti on: 

strDescr := a Me t h od . I n vo ke ( a nObj ec t , [ ] ) . ToSt r i ng; 
dakld: 

strlD := a Me t hod. I nvokef anObj ect , [ ] ) . To St r i ng ; 

What the program fails to do isto check if an attribute is duplicated (thatis, if 

there are multi pie methods marked with the same attri bute, a situation i n 

which you might want to raise an exception). Summing up all of the snippets of 

the previous page, this is the complete code of the Up d at e L i st method: 

procedure TFormDescrAttr. UpdateLi st; 
va r 

anObj ect : TObj ect ; 
context: TRtti Context; 
aType: TRtt i Type; 
attri b: TCustomAt tribute; 
aMethod: TRtti Method; 
s t r De s c r , s t r I D: string; 
begi n 

for a nObj ec t in f Obj ec t s Li s t do 
begi n 

aType := c o n t ex t . Ge t Ty p e ( a nObj ec t . CI a s s I nf o ) ; 
if TypeHasDescri pti on (aType) then 
begi n 

for aMethod in aType. Get Met hods do 

for attrib in a Met hod. Get At t r i but es do 
if attrib is Descri pti onAttri bute then 
case Descri pti onAttri bute(attri b). Ki nd of 
dakClass: ; // ignore 
da k Des c r i pti on: 

// should check if duplicate attribute 
strDescr : = aMet hod. I nvoke( 
a nObj ec t , [ ] ) . To St r i ng ; 
dakld: 

strlD := aMethod. I nvoke( 
a nObj ec t , [ ] ) . To St r i ng ; 

end; 

// done looking for attributes 

II should check if we found anything 

wi t h Li st Vi ewl. I t ems . Add do 

begi n 

Caption : = st r I D; 
Subl terns. Add( st rDescr) ; 
end; 
end; 
end; 

// else ignore the object, could raise an exception 
end; 
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I f this program produces rather uni nteresti ng output, shown below, the way it 
is done is relevant, as I 've marked some classes and two methods of those 
classes with an attribute, and have been ableto process these classes with an 
external algorithm. I n other words, the classes themselves need no specific 
base cl ass, no i nterf ace i mpl ementati on nor any i nternal code to be part of the 
architecture, but only need to declare they want to get involved. The full 
responsi bi I ity for managi ng the cl asses is i n some external code. 

*5) DticnptionAttribulM LsjJUJbSsI ' 



ID 


Qescnpbon 


12*4144 


Wfey 


29137773 


Acre Inc. 



XML Streaming 

One interesting and very ample case for RTTI iscreatingan "external" image of 
an object, for savi ng its status to a fi le or sendi ng it over the wi re to another 
application. Traditionally, the Delphi approach to this problem has been 
streami ng the publ ished properties of an object, the same approach used when 
creating DFM files. Now the RTTI lets you save the actual data of the object, its 
fields, rather than the external interface. This is more powerful, although it can 
lead to extra complexity, for example i n the management of the data of i nternal 
objects. Again, the demo acts as a simple showcase of the technique and doesn't 
delve into all of its implications. 

This exampl es comes i n th ree versi ons, compi I ed i n a si ngl e proj ect for si mpl i - 
city. The first is the traditional Delphi approach based on published properties, 
the second uses the extended RTTI and fields, the third uses attributes to cus- 
tomize the data mappi ng. 

The Trivial XML Writer Class 

To help with the generation of theXM L, I 've based the X ml Persist demo on an 
extended version of aTTr i vi al Xml Wr i ter classl originally wrote in my 
Delphi 2009 Handbook to demonstratetheuseof theTText Wr i t er class. 
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Herel don't want to cover it again. Suffice to say that the class can keep track of 
theXML nodes it opens, thanks to a stack of strings, and close theXML nodes 
in aLIFO (Last In, First Out) order. 23 

To the origi nal cl ass I 've added some I i mi ted formatti ng code and three meth- 
ods for saving an object, based on the three different approaches I 'm going to 
explore in this section. This is the complete class declaration: 
type 

T T r i v i a I X ml Wr i t e r = class 
pr i vat e 

f Writer: TText Writer; 

f Nodes : TSt ac k < s t r i ng>; 

f Owns Te xt Writer: Boolean; 
publ i c 

constructor Create (aWriter: TText Wr iter); overload; 
constructor Create (aStream: TStream); overload; 
destructor Destroy; override; 

procedure WriteStartElement (const sName: string); 
procedure Wri teEndEI ement (flndent: Boolean = False); 
procedure WriteString (const sValue: string); 
procedure Wr i t eObj ect Publ i s hed (AnObj: TObject); 
procedure Wr i t e Ob j ect Rt t i ( An Ob j : TObject); 
procedure Wr i t eObj ect At t r i b (AnObj: TObject); 
function I ndent at i on: string; 
end; 

To get an idea of the code, this is the Wr i t eSt a r t El e men t method, which uses 

the I n d e n t a t i on function for leaving twice as much spaces as the current 

number of nodes on the i nternal stack: 

procedure TTri vi al Xml Wri ter, Wri teStartEl ementf 

const s N a me : string); 
begi n 

f Wr i t e r . Wr i t e (Indentation + ' <' + sName + ' >' ) ; 
f Nodes. Push ( sname) ; 
end; 

You'll fi nd the complete code of the class i n the project source code. 
Classic RTTI -Based Streaming 

After this introduction covering the support class, let me start from the very 
beginning, that is saving an object in an XML- based format using the classic 
RTTI for published properties. 



23 The source code of the TTri vialXmlWriter class of Delphi 2009 Handbook can be found 
at http:// www.marcocantu.com/ code/ dh2009/ ReaderWriter.htm 
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The code of the Wr i t eObj ect Publ i shed method is quite complex and 
requires a bit of explanation. It is based on theTypI nfo unit and uses the low- 
level version of the old RTTI to be able to get the list of published properties for 
a given object (theAnObj parameter), with code I ike: 

nProps := Ge t Ty pe Da t a ( AnOb j , CI a s s I nf o ) A . P r o p Co u n t ; 
Get Mem( Pr opLi st , nProps * SizeOf(Pointer)); 
Get Prop I nf os( AnObj . CI as si nfo, Prop LI st ) ; 
fori := 0 t o nProps - 1 do 



What this does is ask for the number of properties, al locate a data structure of 

the proper size, and fill the data structure with information about the published 

properties. I n case you are wondering could you write this low- level code? Well 

you've j ust found a very good reason why the new RTTI was i ntroduced. For 

each property, the program extracts the value of properties of numeric and 

string types, while it extracts any sub-object and acts recursivelyon it: 

strPropName := UTF8ToStrlng ( P r o p L I s t [ I ] . Na me ) ; 
case Pr op LI s t [ I ] . P r o pTy pe A . Ki nd of 

tklnteger, t k E n u me ration, tkString, tkUStri ng, ...: 

begi n 

WriteStartElement (strPropName); 
Wri teStri ng ( Ge t P r o p Va I u e ( An Ob j , strPropName)); 
Wr i teEndEI ement; 
end; 

t k C I ass: 
begi n 

i nt er na I Obj ec t := Ge t Ob j ec t P r o p ( An Ob j , strPropName); 
// recurse in subclass 
WriteStartElement (strPropName); 

Wr i t eObj ect Publ i s hed ( i nt er nal Obj ect as T Pe r s i s t e n t ) ; 
Wri teEndEI ement (True) ; 

end; 
end; 

There is some extra complexity, but for the sake of the example and to give you 
an idea of the traditional approach, that should be enough. 

To demonstrate the effect of the program I 've written two cl asses (TCo mp a n y 
and T P e r s o n ) adapted from the previous example. This ti me, however, the 
company can have a person assigned to an extra property, called B o s s . I n the 
real world this would be more complex, but for this example it is a reasonable 
assumption. These are the published properties of the two classes: 
type 

TPerson = class (TPersistent) 
publ i shed 

property Name: string read FName write FName; 
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property Country: string read FCountry write FCountry; 
end; 

TCompany = class (TPersi stent) 
publ i shed 

property Name: string read FName write FName; 
property Country: string read FCountry write FCountry; 
property ID: string read FID write FID; 
property Boss: TPerson read FPerson write FPerson; 
end; 

The mai n form of the program has a button used to create and connect two 

objects of these two classes and saving them to an XML stream, which is later 

displayed. The streaming section has the foil owing code: 

ss : = TStringStream. Create; 
x ml Wr i : = TTrivialX ml Wr iter. Create (ss); 
x ml Wr i . Wr i t e S t a r t E I e me n t ( ' c o mp a n y ' ) ; 
xml Wri . Wri teObj ectPubl i shed(aCompany); 
x ml Wr i . Wr i t e E n d E I e me n t ; 

The result is an XML file like: 

<company> 

<Name>ACME I nc. </ Name> 
<Country>Worl dwi de</Country> 
<l D>2 9 0 8 8 8 5 1 </ 1 D> 
<B o s s > 

<Na me >Wi I ey </ Na me > 
<Count ry>Desert </ Count ry> 
</ Bos s > 
</ company > 

Streaming Fields With the New RTTI 

Now that Delphi 2010 provides us with a much higher-level RTTI, I can convert 

the program to use this new RTTI for accessing the published properties. What 

I'm going to do, instead, is to use it for saving the internal representation of the 

object, that is, its private data fields. Not only ami doing something more 

hard-core, but I 'm doing it with much higher-level code. The complete code of 

theWr i t eObj ec t Rt t i method isthe following: 

procedure TTri vi al Xml Wri ter.Wri teObj ectRtti (AnObj : TObject); 
va r 

aCont ext : TRtti Context; 
aType: TRtt i Type; 
a F i el d : TRtti F i el d ; 
begi n 

aType := aCont ext . Get Type ( a nObj . CI a s s Ty pe ) ; 
for a F i el d in aType. Get Fi el ds do 
begi n 



Marco Cantu, Delphi 2010 Handbook 



Chapter 3: Extended RTTI and Attributes - 97 



if a F i el d. F i el dType. I si nstance then 
begi n 

Wri teStartEl ement (aFi el d. Name); 

Wri teObj ectRtti ( a F I e I d . Ge t Va I ue ( a nObj ) , As Ob j e c t ) ; 

Wri teEndEI ement (True); 
end 
else 
begi n 

Wri teStartEl ement (aFi el d. Name); 
Wri teSt r I ng (aFi el d. GetVal ue( anObj ) . To St r I ng) ; 
Wri teEndEI ement; 
end; 
end; 
end; 

The resulting XML is somewhat similar, but somehow less clean as field names 

are generally less readable than property names: 

<c o mp a n y > 

<F Na me>ACME I nc . </ F Na me > 

<F Co u n t r y >Wo rl dwi de</FCountry> 

<FI D>29470148</ Fl D> 

<F P e r s o n > 

< F N a me > Wi I ey</ FName> 
<FCount ry>Desert</ FCount ry> 
</ F P e r s o n > 
</ company > 

Another big difference, though, isthat in this case the classes didn't need to 
inherit from theT Per s i stent class or be compiled with any special option. 

Using Attributes to Customize Streaming 

Beside the problem with the tag names, there is another issue I haven't men- 
tioned. Using XML tag names which are actually compiled symbols is far from 
a good idea. Also, i n the code there is no way to exclude some properties 24 or 
fields from XM L-base streami ng. These are issues we can address usi ng attrib- 
utes, although the drawback will be having to use them quite heavily in the 
declaration of our classes, a coding style I don't like much. For the new version 
of the code, I 've defined an attribute constructor with an optional parameter: 
type 

x ml At tribute = class (TCustomAttrlbute) 
pr i vat e 

f T a g : string; 
public 



24 Delphi properties streaming can Decontrolled usingthes t o r e d directive, which can be 
read using the Typlnfo unit. Still, this solution is far from simple and clean, even if the 
DFM streaming mechanism uses it effectively. 
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constructor Create (strTag: string = ''); 
property TagName: string read f T a g ; 
end; 

The attri butes- based streami ng code i s a vari ati on of the I ast versi on based on 

the extended RTTI . The only difference is that now the program calls the 

CheckXml At t r helper function to verify if thefield hasthexml attributeand 

the (optional) tag name decoration: 

procedure TTri vi al Xml Wri ter.Wri teObj ectAttri b(AnObj : TObject); 
va r 

aCont ext : TRtti Context; 
aType: TRtt i Type; 
a F i el d : TRtti F i el d ; 
strTagName: string; 
begi n 

aType := aCont ext . Get Type ( a nObj . CI a s s Ty pe ) ; 
for a F i el d in aType. Get Fi el ds do 
begi n 

if CheckXml At tr (aField, strTagName) then 
begi n 

if aFi el d. Fi el dType. I si nstance then 
begi n 

Wri teStartEl ement (strTagName); 

Wr i t eObj ect At t r i b ( a F i e I d . Ge t Va I ue ( a nObj ) , As Ob j ec t ) ; 

Wri teEndEI ement (True); 
end 
else 
begi n 

Wri teStartEl ement (strTagName); 
Wri teSt ri ng (aFi el d. GetVal ue( anObj ) . To St ri ng) ; 
Wri teEndEI ement; 
end; 
end; 
end; 
end; 

The most relevant code is in theChec k X ml At t r helper function: 

function Chec k X ml At t r (aField: TRtti F i el d ; 

var strTag: string): Boolean; 
va r 

attri b: TCust omAt tribute; 
begi n 

Result : = Fal se; 

for attrib in a F i e I d . Get At t r i b ut es do 
if attrib is Xml Attribute then 
begi n 

strTag := x ml At t r i b u t e ( a 1 1 r i b ) . Ta g Na me ; 
if strTag = 11 then // default value 

strTag : = aField. Na me; 
Exit (True); 
end; 

end; 
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Fields without the XML attribute are ignored and the tag used in the XML out- 
put is customizable. To demonstrate this, the program has the following classes 
(th i s ti me I ' ve omi tted the publ i shed properti es from the I i sti ng, as they are not 
relevant): 
type 

TAt t r Person = class 
pr i vat e 

[ x ml ( ' Name')] 
F N a me : string; 
[xml] 

F Country: string; 



TAt t r Company = class 
pr i vat e 

[xml ( ' Company Name' ) ] 

F N a me : string; 

[xml ('Country')] 

F Country: string; 

FID: string; // omi 1 1 ed 

[xml ( ' TheBoss' ) ] 

F Pe r s o n : TAt t r P e r s o n ; 

With these declarations, theXML output will look I ike the foil owing (notice the 
tag name, the fact the I D is omitted, and the (bad looking) default name for the 
FCount ry field): 
<company> 

<CompanyName>ACME I nc. </CompanyName> 
<Country>Worl d w i de</Country> 
<T h e B o s s > 

<Na me >WI I ey </ Na me > 

<FCountry>Desert</FCountry> 
</ TheBoss > 
</ company > 

The difference here is we can be very flexible about which fields to include and 
how to name them in the XML, something the previous versions didn't allow. 

Even if this is just a very skeletal implementation, I think that giving you the 
opportunity to see the fi nal versi on bei ng created step by step starti ng with the 
classic RTTI has given you agood feeling of the differences among the various 
techniques. What is important to keep in mind, infact, isthatisitnotagiven 
that usi ng attri butes wi 1 1 be always the best solution! On the other hand, it 
should be clear that RTTI and attributes add a lot of power and flexibility in any 
scenario i n which you need to i nspect the structure of an unknown object at run 
ti me. 
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What's Next 

For its long term viability, Delphi must provide new language features that can 
be used as a renewed foundation for the development of modern frameworks. 
The growth of framework- based code is quite significant both i n thej ava world 
and inthe.NET environment, and missing the language features that are at the 
foundations of these frameworks was quitea negative point for Delphi. Now 
with generics and anonymous methods introduced in Delphi 2009 and attrib- 
utes added to Delphi 2010 the gap is reducing significantly. So I hopethatthe 
next few years wi 1 1 see the start of new Del phi frameworks or the port to Del phi 
of existing open source frameworks used by other environments. Both Embar- 
cadero Technologies as a company and the Delphi community at large should 
push for this goal. 

That's why the current chapter is probably the most relevant (and also one of 
thelongest) of the entire book. In it I've fully delved into the new Extended 
RTTI of Delphi 2010 and its Attribute support. There are some other new com- 
piler features that are worth exploring, which is what I'll do in the first part of 
the next chapter. 

The second part of Chapter 4 focuses on changes to the Run Time Library 
(RTL, for short). I n Chapter 5 1 'II start exploring new features of the Visual 
Component Library (VCL, for short). 
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Chapter 4: More 
On The Compiler 
And The RTL 

If Extended RTTI and attribute support are the most significant new features of 
the Del phi 2010 compiler, there are three other important enhancements: the 
ability to access the object behind an i nterf ace reference, delayed loading of 
DLL functions, and class constructors. I 'II look at these features in the first part 
of this chapter. The second part of the chapter wi 1 1 focus on the RTL and the 
new lOUtils unit, which defines classes for files and folders. 



New Compiler Features 

While it is possiblefor third- parties to provide custom components or extend 
the IDE, the compi ler is the core capabi lity that only the R&D Team can extend. 
That's why each change at the compi ler level is worth special consideration. 

Marco Cantu, Delphi 2010 Handbook 



104 - Chapter 4: More on the Compiler and the RTL 

Version 

First of all, in case you need to have some code specifically tied to Delphi 2010, 
consider that whilethe IDE version number is 14, the compiler version number 
(dating back to the original Turbo Pascal) is 21 The corresponding compiler 
define is VER2 10 , so you can have code that compiles only for this version with: 

| {$1 FDEF VER210} 

Extracting Objects from Interface References 

1 1 was the case for many versions of Del phi , that when you assign an object to 
an i nterface vari abl e, there was no way to access the ori gi nal obj ect. At ti mes, 
Delphi developers would add aGet Obj ect method to their interfaces to per- 
form the operation, but that is quite an odd design. 

For the first time si nee interfaces were introduced, Delphi 2010 adds support 
for casti ng interface references back to the origi nal object to which they have 
been assigned. There are three separate operations you can use: 

• You can write an i s test to verify that an object of the given type can can 
i ndeed be extracted from the i nterface reference: 

| i n t f V a r is T My Ob j ect. 

• You can write an as cast to perform the type cast, raising an exception in 
case of an error: 

| i n t f V a r as T My Ob j ect . 

• You can write a hard type cast to perform the same conversion, returni ng a 
nil pointer in case of an error: 

| T My Ob j ect ( i nt f Var ) 

I n every case, the type cast operati on works on I y i f the i nterface was ori gi nal I y 
obtained fromaDelphi object, and notfromaCOM server. Note also that you 
can not only cast to the exact class of the original object, but also to one of its 
base classes (foil owing standard class compatibility rules for derived classes). 

As an example, consider having the following si mpleinterface and implement- 
ati on cl ass ( part of the Obj F roml ntf proj ect) : 
type 

ITestlntf = interface (I I nterface) 

/ ' {2A77A244- DC85- 4 6 BE - B 9 8 E - A9 3 9 2 E F 2A7A7 } 1 ] 

procedure Do So me thing; 
end; 
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TTestlmpI = class (Tl nterfacedObj ect, ITestlntf) 
publ i c 

procedure Do So me thing; 

procedure DoSomethi ngEI se; // not in interface 
destructor Destroy; override; 
end; 

With these definitions you can now define an interface variable, assign an 
object to it, and use it also to invoke the method not in the i nterface, with the 
new cast: 
va r 

i ntf : I Test I ntf ; 
begi n 

intf : = TTestlmpI .Create; 
i ntf. Do So met hi ng; 

(intf as TTestl mpl ). DoSomethi ngEI se; 

You can also write the code in the foil owing way, using an i s test and a direct 
cast, and you can al ways cast to a base cl ass of the actual cl ass of the obj ect: 
va r 

intf: ITestlntf; 
original: TObj e c t ; 
begi n 

intf : = TTestl mp I. Create; 

i ntf. Do So met hi ng; 

if intf is TObj ect then 

original : = T 0 b j e c t (intf); 
(original as TTestl mpl ). DoSomethi ngEI se; 

Considering that a direct cast returns nil if not successful, you could also write 

thecodeasfollows(withoutthepreviousi s test): 

original : = TObj ect (intf); 
if Assi gned (original) t hen 

(original as TTestl mpl ). DoSomethi ngEI se; 

N oti ce that assi gn i ng the obj ect extracted from the i nterface to a vari abl e 
exposes you to reference counti ng issues: when the i nterface is set to n i I or 
goes out of scope, the obj ect i s actual I y del eted and the vari abl e refer ri ng to i t 
will become invalid. You'll find the code highlighting the problem in the 
bt nRef Count I ssueCI i ck event handler of the example. 

Technically, the three operations (as cast, direct conversion, i s test) areimple- 
mented by three new global routi nes of the System unit: 

function _ I nt f As Cl a s s ( c o ns t Intf: I I nterface; 

Parent : "TCI ass) : TObj ect ; 
function _ Saf el nt f As Cl a s s ( c o ns t Intf: I I nterface; 

Parent : "TCI ass) : TObj ect ; 
function _l nt f I sCI ass ( const Intf: I I nterface; 

Parent: TCIass): Boolean; 
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Class Constructors (and Destructors) 

Class constructors are a new feature that has been borrowed from the .N ET 
environment and were already available in Delphi for .NET. A class constructor 
has nothi ng to to with a standard constructor (or i nstance constructor) : 1 1 is 
merely code used to initialize the class itself once (generally class data or other 
global settings) before the class is used. 

In other words, a class constructor is an alternative to the unit initialization 
code. I n case both exist (in a unit), the class constructor will be executed first. 
At the opposite, you can def i ne a cl ass destructor that wi 1 1 be executed after the 
finalization code. 

A significant difference, however, is that while the unit initialization code is 
invariably executed if the unit iscompiled in the program, the class constructor 
and destructor are linked only if the class is actually used. This means that the 
use of class constructor is much more I inker friendly than the use of initializa- 
tion code. With class constructors and destructors, if the type is not linked the 
initialization code is not part of the program and not executed; in the tradi- 
tional case the opposite is true, the initialization code might even cause the 
linker to bring in some of the class code, even if it is never actually used 25 . 

I n terms of code, you can write the foil owing (taken from theClassCtor demo): 
type 

TTest CI ass = class 

public 

class var 

StartTime: TDateTime; 
E n d T i me : T Da t e T i me ; 
publ I c 

class constructor Create; 
class dest r uct or Dest roy; 
end; 

The class has two class data fields, initialized by the class constructor, and 

modified by a class destructor, while the i ni ti al i zati on andf i n a I i z a t i on 

sections of the unit uses these data fields: 

class constructor TTestCI ass. Create; 
begl n 

St a r t Ti me : = Now; 
end; 



25 I n practical terms, this happens in Delphi 2010 for the new gesturing framework, which 
is not compi led into the executable if not used. 
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class destructor TTestCI ass. Destroy; 
begi n 

EndTime : = Now; 
end; 

initialization 

ShowMessage (TimeToStr (TTestCI ass. StartTi me)); 

f i nal i zat i on 

ShowMessage (TimeToStr (TTestCI ass. EndTime)); 

What happens is that the start up sequence works as expected, with the class 
data already avail able as you show the information. When closing, instead, the 
ShowMessage call isexecuted before the value is assigned by the class 
destructor, which isexecuted at the very end. 

Notice that you can give the class constructor and destructor any name, 
although Cr e at e andDestroy would be very good defaults. You cannot, how- 
ever, defi ne multi pie class constructors or destructors. I f you try, the compi ler 
will issue the foil owing error message: 

[ DCC Error] CI assCtorMai nForm. pas( 34) : E 2 3 5 9 Multiple class 
constructors in class TTestCI ass: Create and Foo 

There are a few RTL classes that already take advantage of this new language 

feature, I i ke the Except i on class that defines both a class constructor (with the 

code below) and a class destructor: 

class constructor Except i on. Creat e; 
begi n 

I ni tExcepti ons; 
end; 

Thel ni tExcepti ons procedure was previously called in the initialization sec- 
tion of the SysUti Is unit. Ingeneral, I think that using class constructors and 
destructors is better than using unit initialization and termination. I n most 
cases, this is only syntactic sugar, so I won't go back and change existi ng code. 
However, if you face the risk of initializing data structures you'll never used 
( because no cl ass of that type i s ever created ) movi ng to cl ass constructors wi 1 1 
provide a defi nitive advantage. 

Class Constructors for Generic Classes 

A very i nteresti ng case ari ses when you defi ne a cl ass constructor for a generi c 
class. In fact, one such constructor is generated by the compi ler and called for 
each generic class instance, that is, for each actual type defined using the gen- 
eric template. This is quite interesting, because it would be quite complex to 
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execute initialization code for each actual instance of the generic class you are 
going to create in your program without class constructor. 

As an example, consider a generic class with some class data. You'll get an 
instance of this class data for each generic class instance. If you need to assign 
an initial value to this class data, you cannot use the unit initialization code, as 
in the unit defining the generic class you don't know which actual classes you 
are going to need. 

The following is a bare bones example of a generic class with a class constructor 
used to initialize the Da t a Si ze cl ass field, taken from the GenericClassCtor 
example: 
type 

TGeneri cWi thCI assCtor <T> = class 
pr i vat e 
FData: T; 

procedure Set Dat a( const Value: T) ; 
public 

class constructor Create; 

property Data: T read FData write Set Dat a ; 

class va r 

DataSize: Integer; 

end; 

This is the code of the generic class constructor, which uses an internal string 

list (see the full source code for implementation details) for keepi ng track of 

whi ch cl ass constructors are actual I y cal I ed : 

class constructor TGeneri cWi thCI assCtor<T>. Create; 
begi n 

Dat a S i ze : = Si zeOf ( T) ; 
Li stSequence. Add( Cl assMame) ; 
end; 

The demo program creates and uses a couple of instances of the generic class, 
and also declares the data type for a third, which is removed by the linker: 
va r 

genlnt: TGeneri cWi thCI assCtor < S ma I I I n t > ; 
genStr: TGeneri cWi thCI assCtor < s t r i n g > ; 
type 

TGenDouble = TGeneri cWi thCI assCtor <Do u b I e >; 

I f you ask the program to show the contents of the Li stSequence stri ng I ist, 

you'll see only the types that have actually been initialized: 

TGeneri cWi thCI assCtor<System. Smal I I nt> 
TGeneri cWi thCI assCtor<System. stri ng> 

H owever, if you create generic i nstances based on the same data type i n differ- 
ent units, the linker might not work as expected and you'll have multiple calls 
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to the same generic class constructor 26 (or, to be more precise, two generic class 

constructors for the same type). I've added a procedurecal led Us el ess inthe 

secondary unit of this examplethat, when uncommented, will highlight the 

problem, with an initialization sequence I ike: 

TGeneri cWi thCI assCtor<System. stri ng> 
I TGe ne r i c Wi t hCI a s s Ct o r <S y s t e m. S ma I I I n t > 
| TGeneri c Wi thCI assCtor<System, stri ng> 

Delayed Loading of DLL Functions 

I n the Wi ndows operati ng system, there are two ways to i nvoke an API function 
of the Windows SDK (or any other DLL): you can let the application loader 
resolve al I references to external functions or you can write specific code that 
looks for a function and executes it if available. The former code is easier to 
write, as all you need isthe external function declaration, but if the library or 
even j ust one of the functions you want to cal I is not avai I able (a frequent case if 
your program has to work on multiple versions of the operating system), your 
program will not beableto start. Dynamic loading allows for more flexibility, 
but implies loading the library manually, using theGet Proc Address API for 
finding the fundi on you want to call, and invoking it after casting the pointer to 
the proper type. This ki nd of code is quite cumbersome, and recent versions of 
Delphi started adding more and more of it into the VCL, to provide support for 
Windows Vista (and now Windows 7) features from within applications that 
still have to work on Windows XP or Windows 2000. 

That's why it is good that the Delphi 2010 compiler and linker have added sup- 
port for a featu re now avai I abl e at the operati ng system I evel and al ready used 
by some C++ compilers, the delayed loading of functions until the time they are 
called. The aim of this declaration is not to avoid the implicit loading of the 
DLL, which takes place anyway, but to allow the delayed binding of that specific 
function within the DLL. 

You basi cal I y wri te the code i n a way that's very si mi I ar to the cl assi c executi on 
of DLL function, but the fundi on address is resolved the first time the fundi on 



26 It isnoteasytoaddressasimilar problem. Toavoid a repeated initialization, you might 
want to check if the class constructor has already been executed. I n general, though, this 
problem is part of a more comprehensive limitation of generic classes and the linkers in- 
abi I i ty to opti mi ze them. 



Marco Cantu, Delphi 2010 Handbook 



110 - Chapter 4: More on the Compiler and the RTL 

iscalled and not at load time. This means that if the function is not available 
you get a run-time exception, EExternal Excepti on 27 . However, you can gen- 
erally verify the current version of the operati ng system or the version of the 
specific library you are calling, and decide in advance whether you want to 
make the call or not. 

From the Delphi perspective, the only difference is in the declaration of the 

external function. Rather than writing (as you can see in the Windows unit): 

function MessageBox; 

external u s e r 3 2 name ' Mes s ageBoxW ; 

You can now write (again, from an actual example in the Windows unit): 

Ifuncti on Wi ndowFromPhysi cal Poi nt; 
ext er nal user 32 

name ' Wi ndowFromPhysi cal Poi nt ' delayed; 

At run time, considering that the API has been added to Vista (that is, Windows 

6.0) for the first time, you might want to write code I ike the foil owing taken 

from the Delayed Loading example: 

i f CheckWi n 3 2 Ve r s i on ( 6, 0) then 
begl n 

hwnd : = Wi ndowFromPhysi cal Poi nt (aPoint); 

This is nowhere near the amount of code you had to write in previous versions 
of Delphi to obtain the same behavior. NeedlesstosaythattheVCL source code 
has been significantly updated to use this feature wherever possible, and with 
the addition of many core API functions that were previously omitted to avoid 
i ncompati bi I ities with older versions of the operati ng system. 

Another relevant observation is that you can use the same mechanism when 
building your own DLLs and calling them in Delphi, providing a single execut- 
ablethatcan bind to multiple versions of thesameDLL as long as you use 
delayed loading for the new functions. Unluckily, the same doesn't applyto 
packages, but the new Extended RTTI offers enough capabilities for working 
with packages dynamically that we can also bequite happy about the Del phi 
2010 improvements in that area. 



27 If you want something more specific and easier to handle at a global level than an excep- 
tion, you can hook into the error mechanism for the delayed loading call, as explained by 
Allen Bauer in hisblogpost: http://blogs.embarcadero.com/abauer/2009/08/29/38896 
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Scoped Enumerators 

Although it was introduced in Delphi 2009, scoped enumerations have been 
hidden enough and I failed to cover them in my "Delphi 2009 H andbook", so 
I'm sure it makes sense to cover them here. Traditionally in Delphi the values 
of an enumeration become global constants you can use freely in your code. 
This could not be changed, for backward compatibility. The Delphi compiler, 
however, has a new directive, $SCOPEDENUMS, that changes the behavior of 
enumerations making it compulsory to refer to them with a type prefix 28 . 

H avi ng an absol ute name to refer to enumerated val ues removes the risk of a 
conflict, could let you avoid using the initial prefix of the enumerated val ues as 
a way to differentiate with other enumerations, and makes the code more read- 
able, even if much longer to write. Too bad that Code Completion doesn't seem 
to recognize scoped enumerations, so you actually need to enter the entire type 
and value manually. 

As an example, thelOUtils unit (see later in this chapter) defined this type: 

I {$SC0PEDENUMS ON} 
type 

TSearchOpti on = (soTopDi rectoryOnl y, soAl I Di rectori es) ; 

This means you cannot refer to the second values ass oAl I Di rectori es , but 
you have to refer to the it with its complete name: 

|TSearchOpti on.soAl I Di rectori es 

This probably sounds quite odd to most Delphi developers, but I guess we'll 
have to get used to it, whether you like it or not. 



The With Statement Now Preserves Read 
Only Properties 

Beside the various extensions covered so far, the compiler in Delphi 2010 has a 
relevant fix... which can affect existing programs that exploited this unwanted 
opportunity as if it were a feature. I n short, if you have a wi t h statement refer- 
ri ng to a read-only record property, you cannot modify the record members any 
more. Again, this is a reasonablefix, but it might affect existing code (and did 
affect the source of some third party controls). Hereisan example, which isthe 



28 This is exactl y how C# i n var i abl y works. 
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ReadOnlyRecord project in the book's source code. Suppose you have a record 
I i ke the fol lowi ng (the effect is the same for a packed record) : 
type 

T My Point = record 

X: Integer; 

Y: Integer; 
end; 

Suppose you have a class that uses this record as value of a read-only property: 
type 

T My F i xedRect = class 
pr i vat e 

f Bot t omRi ght : TMyPoi nt ; 

f TopLef t : TMyPoi nt ; 
publ i c 

constructor Create (a, b, c, d: Integer); 
property TopLef t : TMyPoi n t read fTopLeft; 
property BottomRight: TMyPoi nt read fBottomRight; 
end; 

Any code that tries to access the individual element of the read-only record 
property would notcompilein Delphi 2009, nor itdoesin Delphi 2010: 

va r 

a Re c t : TMyFi xedRect ; 
begi n 

aRect := TMyFi xedRect . Create! 1 0, 1 0, 1 0 0, 1 0 0 ); 
aRect . TopLef t . X : = 20; 

However, the fol I owing code would have worked in Delphi 2009: 

wi t h aRect . TopLef t do 
X : = 20; 

In Delphi 2010, this causes a compiler error: 

[ DCC Error] Rea dOn I y Rec o r d Ma i n F o r m. p a s ( 5 1 ) : 
E2064 Left side cannot be assigned to 

Of course, if you extract the record and modify it, you are modifyi ng a copy, so 

the original read-only value is not affected, as another code snippet of the demo 

program demonstrates: 

aPoi nt : = aRect . TopLef t ; 
aPoi nt . X : = 20; 

ShowMessage (IntToStr ( aRect . TopLef t . X) ) ; 

Apparentl y thi s change was made because si mi I ar code i n the context of generi c 
records caused significant problems. While it is a positive change (making the 
code more robust and clean) it has the drawback of not being backward com- 
patible: Existing Delphi code might fail to compile, although the workaround 
would probably be reasonably simple. 



Marco Cantu, Delphi 2010 Handbook 



Chapter 4: More on the Compiler and the RTL - 113 



New Run Time Library Features 

Every ti me the Del phi compi ler gets updated, there are extensions of the Run 
Time Library (RTL) that go along with them. I n this release, for example, the 
System unit defines new types like theTVi si bi I i tyCI asses enumeration 
and theTCu s t o mAt t r i bute class, which complement the Extended RTTI sup- 
port. There are other trends i n the RTL that are worth explori ng, beside looki ng 
at specific new features and a few brand new units. 

RTL Trends 

There are a few rel evant trends i n the Del phi product that show up i n the RTL . 
The first is certainly the cross-platform trend. In dozens and dozens of 
places of the RTL units source code you'll see along with L I NUX conditional 
compilation statements (which were never removed from the Kylix 29 days) 
some new MACOSX conditional compilation statements. Support for these two 
platforms is expected in a future version of Delphi. As an example, consider the 
following definition for thes Li ne Break global constant: 
const 

sLi neBreak = {$1 FDEF LINUX} Ansi Char( #10) { $ENDI F } 
{ $1 FDEF MSWINDOWS} Ansi Stri ng(#13#10) { $ENDI F } 
{ $1 FDEF MACOSX} Ansi Char( #10) {$ENDIF}; 

Another trend is the focus on efficient code. There are countless new inlined 
functions at the RTL level . Agai n, as an example, i n the DateUti Is unit (for pro- 
cessi ng date and ti me val ues) 27 existi ng functions have been marked i nl i ne i n 
Delphi 2010. 

A third trend is localization support: This has been improved by using the 
operating system U I Local e property and the complete language-country 
names (likefr-FR) to determine which localized resource DLL to use. 



29 Kylix was a version of Delphi for Linux. Not only the compi ler could produce Linux ex- 
ecutables (limited to the I ntel platform), but the entire I DE could run under Linux as 
host operating system. Despite three versions, Kylix never caught on, also because of 
some instabi I ity of the IDE. That's probably one of the reasons why E mbarcadero men- 
tioned its future cross-platform versions of Delphi will use the Windows I DE and let de- 
velopers cross-compile to other operating systems. 
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A fourth trend is the slow conversion to code based on generics in the RTL. 
For example, in the System unit there is now the declaration of a generic typed 
dynamic array, TAr r a y <T > : 
type 

TAr r a y <T > = array of T; 



Browsing Existing Units 

Beside compi I er- related features and trend- setting features, there are many 
other extensions to the RTL, some of which are worth mentioning: 

• TheT S t r i n g B u i I d e r class has a new Clear method, that removes any 
data in the current buffer. 

• In theTypes unit there a new global function called Pt I nCi r c I e , that 
clones the existingPt I nRect function. 

• As al ready menti oned i n Chapter 2, the TThr ead cl ass has a new stati c cl ass 
method to help with naming threads, NameThreadFor Debuggi ng. 

• Also, the Res u me andSuspend methodsof theTThr ead class are now deprec- 
ated 30 . In case you initially create the thread in asuspended state, you should use 
the new Start method i nstead of R e s u me . 

• TheT C ustoml ni Fi I e class has been extended with a new method, 
ReadSubSecti o n s , to i mprove compati bi I ity with registry access usi ng the 
classTReg I ni F i I e . 

• TheT Re g i s t r y class, in turn, has improved error management, with the 
new properties LastError and LastErrorMsg. Of course, the methods of 
the class now extensively check for errors, making it much more robust to 
work with. 

There are a couple of other new features that are i nteresti ng to notice, as they 
have quite an ironic spin. 



30 TheResjme method was deprecated becauseit wasfound to beunsafe, leadingto 
memory corruption under certain circumstances. As I learned from Mason Wheeler, 
"Basic idea is that Res ume un-suspends the thread, and then changes one of the 
thread's fields, but if you resumeand then the thread terminates and frees itself imme- 
diately, beforetheffes ume method reaches that point, you'reoverwriting freed 
memory which may have been re-allocated already in a high-traffic environment." 
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The first is that the SysU tils unit has a new data type, which can be considered 
as a Boolean value with a spin. Called TUnc er t a i n St a t e and used bytheDir- 
ect2D unit, it is a scoped enumeration 31 defined as: 
type 

TUncertai nState = (Maybe, Yes, No); 

The second side note is that Douglas Adams fans should look to the implement- 
ation of theGet HashCodeCI ass function... which uses 42 as return value in 
given circumstances, rather than causing an exception as it did in the past. I 
wonder if 42 is just a random non-zero value, of if there is any reason it was 
picked... other then being the "Answer to the Ultimate Question of Life, the 
Universe, and Everything" 32 . 

Collections and Containers 

Another set of RTL updates relates to col lections and containers. The T Li st 
class defines a new sorting method, called S o r t L i s t , which takes an anonym- 
ous method as parameter. So in case of aT L i s t storing numbers (as in the 
bt nSort Li stAnonCI i ck event handler of the RtlLists example, you can write: 
va r 

a L i st: T L i st ; 
begi n 

a L i st. SortLi st ( 

function (Iteml, Item2: Pointer): Integer 
begi n 

if Integer(lteml) > Integer (Item2) then 
Result : = 1 

else if Integer(lteml) < Integer (Item2) then 

Result : = - 1 
else 

Res ul t : = 0; 
end) ; 

TheTLi st class has also three other new methods that let you find theposition 
of an element (or extract it or remove it) starting from the end of thelist rather 
than the beginning. Actually the three methods, listed below, have a 
T D i recti on parameter that lets you specify the standard (F r o mBeg i n ) or 
reverse (F r o mE n d ) sequence: 



31 Scoped enumerations were introduced in first part of this chapter. 

32 According to Douglas Adams in 'The Hitchhiker's Guideto the Galaxy". 
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function Extradite m( Item: Pointer; 

Direction: TDi recti on) : Pointer; 
function Index Of ltem( Item: Pointer; 

Direction: TDi recti on) : Integer; 
function Re mo v e I t e m( I t e m: Pointer; 

Direction: TDi recti on) : Integer; 

The RtlLists project has an example of the usage of I ndexOf I t em, in which the 
program adds 50 consecutive numbers and then repeats the number one, and 
you can search for the two occurrences of the val ue one from the begi nni ng or 
from the end: 
va r 

a L i st: TLi st ; 
I : Integer; 
begi n 

fori : = 1 t o 50 do 

a L i st . Ad d ( Poi nt er ( I ) ) ; 
a L i st. Add ( Poi nter ( 1) ) ; 
Log ( ' I ndexOf: ' + I ntToStr ( 

a L i st. Index Of (Pointer (1)))); 
Log ( ' I ndexOf 1 1 em (FromEndj: ' + I nt To St r ( 

a L i st. Index Of I t e m( Pointer (1), FromEnd))); 

This produces, not surprisingly, the following output: 

I ndexOf : 0 
| I ndexOf I t em ( Fr omEnd) : 5 0 

The same three methods are available also in the inheri ted T Ob j ectLi st, 
TCI as s L i s t , and T Co mponent Li st classes, defined in the Contnrs unit. 

These new methods are not part of the generi c versi on of the T L i s t cl ass, 
TL i s t <T>, which already had a L as 1 1 ndex Of method since it was introduced 
in Delphi 2009 33 . ThegenericTL i s t <T>, however, has its own four new meth- 
ods, two for movi ng items and two for accessi ng the f i rst and I ast ones: 

procedure Exchangef I ndexl, I n d e x 2 : Integer); 
procedure Move( Cur I ndex, Ne wl ndex: Integer); 
f unct ion First: T; 
function Last : T; 



33 I find it quiteodd that the method names of these two strictly related classes, TL i st and 
TLi s t < T > are not kept i n sync as much as possi bl e. Porti ng code from T L i s t code to 
the generic version of the container is harder than it should be. 
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Discovering New Units 

In Delphi 2010, the RTL not only has some new capabilities, but also four 
brand new units. We have al ready covered one of them, the Rtti unit, i n 
Chapter 3. Here come the other three new RTL u n i ts ( 1 1 1 1 list new Windows API 
translation headers in a specific section in the next chapter). 

The I OUti Is unit defi nes a nice set of classes for managi ng the fi le system, 
TDi rectory, TPath, and T F i I e , and wi 1 1 be covered i n a fol lowi ng section. 

TheTimeSpan unitdefinestheTTi meSpan record, si mil ar to the corres- 
pondi ng.NET data structure, and used to express a ti me difference rather than 
an absolute time value. The time is stored insideaTTi meSpan in terms of tens 
of thousandths of a millisecond, that is ten thousands ticks correspond to one 
millisecond. Compared to a T D a t e T i me, which represent the ti me usi ng the 
deci mal part of a floati ng poi nt number, a T T i me S p a n is way more accurate. 

The Diagnostics unit defines a handy T S t o p Wa t c h record, which can be used 
to ti me an algorithm i n a rather precise way, as it uses system ticks and cal Is the 
QueryPerf or manceCount er API to convert ticks to milliseconds in an accur- 
ate way. To enable the higher quality measurement, you have to turn on the 
class property I sHi ghResol uti on. 

Using the TStopWatch Class 

Here is a usage test (from the StopWatchTest example): 
va r 

s w: T S t o p Wa t c h ; 
begi n 

sw := TStopwatch. Create; 

s w. Start; 

// code you want to time 
sw. St op; 

// read elapsed t i me 
sw. El apsedMi I I i seconds 
s w. El a ps edTI c k s 

The fi rst I i ne i nitial izes the frequency counter (dependi ng on the high resol u- 
tion setting) and zeros the stop watch (as local records are not initialized to 
zero), the second starts it. As an alternative you can call the combined 
St a r t New constructor. 
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N oti ce you can Start and S t o p the Stop Watch many ti mes i n a sessi on : E ach 
ti me i nterval will be added. However, you can get the current elapsed time (in 
ticks, milliseconds, or the new and just introduced TT i me S p a n structure) also 
whiletheStop Watch is running. With this in mind you can trim the code to: 
va r 

sw: TSt op Watch; 
begi n 

sw := TStopwatch. StartNew; 

// code you want to time 
sw. El a p s e d T i c k s 



The I nput/ Output Utilities Unit 

One of the most interesting additions to the Del phi 2010 Run Time Library, not 
tied to compiler changes or other new features, isthelOUtils unit. This unit has 
three records mostly defining class methods, which are compatible with the 
corresponding .NET classes: 

• T D i r e c t o r y matches System. I 0. Di rectory 
. TPat h matchesSyst em. I 0. Pat h 

• T F i I e matches System. 10. File 

While it is quite obvious that TDi rectory is for browsing folder and finding its 
fi les and sub-folders, it might not be so clear what is the difference between a 
TPath andTFi I e . The former is used for manipulatingfilenameand directory 
names, with methods for extracting the drive, filename with no path, extension 
and the like, but also for manipulating UNC paths. TheTF i I e record, instead, 
lets you check thefile time stamps and attributes, but also manipulate a file, 
writi ng to it or copyi ng it. 

As usual, it can be worth looking at an example. TheloFileslnFolder program 
can extract all of the sub-folders of a given file and it can grab all of the files 
with a given extension available under that folder. 

The program starts by filling an edit box with the Documents folder of the cur- 
rent user. I used theSh Get Fol der Pat h API oftheShlObj unit (and not that of 
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theS HF o I der unit, avail able for compatibility with very old versions of Win- 
dows 34 ), to get the folder path: 

procedure TForml oFi I es. FormCreate(Sender: T Object); 
va r 

szBufferW: string; 
begi n 

Set Length ( s z B u f f e r W, MAX PATH) ; 
01 eChec k ( SHGet Fol d e r Pa t h" ( Ha n d I e , 

CSI DL_ MYDOCUMEMTS , 0, 0, PChar(szBjfferW))); 
edBaseFol der. Text := string (szBufferW); 
end; 



Extracting Subfolders 

Of course, you can change that initial folder name to something more appropri- 
ate. The program can fill a list box with the list of the folders under that 
directory, by using theGet Di r ec t o r i es method of TDi rectory with the 
TSearchOpti on. s o A I I Di rectori es 35 parameter and enumerating the array 
of stri ngs that it returns: 

procedure TF or ml oF i I es . bt nS ubf o I der s CI i c k ( Sende r : TObject); 
va r 

pathList: TStri ngDynArray; 
strPath: string; 
begi n 

if TDi r ec t o r y . Exi s t s ( e d Ba s e F o I d e r . Tex t ) then 
begi n 

Li stBoxl. Items. CI ear; 

pathList := T Di r e c t o r y . Ge t Di r e c t o r i e s ( ed Ba s e F o I d e r . Te x t , 

TSearchOpti on.soAl I Di rectori es, ni I ); 
for strPath in pathList do 

Li st Box 1. I t ems. Add (strPath) ; 

end; 
end; 



Searching Files 

A second button of the program lets you get al I of the fi les of those folders, by 
scanning each directory with a Ge t F i I e s call based on a given mask. You can 



34 I blogged about the problem of writing this S HGet Fol d e r Pa t h call at 
http:// blog.marcocantu.com/ blog/ SHGetFolderPath_ Default_ User.html 

35 Thel OUti I s usesscoped enumerators, ascovered earlier in thischapter, so you haveto 
prefix the enumerated val ues with the type name. 
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have more complex fi Iteri ng by passi ng an anonymous method of type 
T F i I t e r P r e d i c a t e to an overloaded version of Ge t F i I e s . 

This example uses the simpler mask-based filtering and populates an internal 
stri ng I i st. The el ements of thi s stri ng I i st are then copi ed to the user i nterface 
after removing the full path, keeping only the file name. As you call the 
GetDi rectori es method you get only the sub- folders, but not the current one. 
This is why the program searches in the current folder first and then looks into 
each sub-folder: 

procedure TForml oFi I es. btnPasFi I esCI i ck(Sender: TObject); 
va r 

pathList, filesList: TStri ngDynArray; 
strPath, strFile: string; 
begi n 

if TDi rectory. Exi sts ( e d Ba s e F o I d e r . Tex t ) then 
begi n 

// clean up 

Li stBoxl. Items. CI ear; 

// search in the given folder 

filesList := TDi r ec t o r y . Ge t F i I es ( edBaseFol der . Text , '*.pas')\ 
for strFile in filesList do 
s F i I e s L i st. Ad d ( strFile); 

// search in all subf ol der s 

pathList := T Di r e c t o r y . Ge t Di r e c t o r i e s ( ed Ba s e F o I d e r . Te x t , 

TSearchOpti on.soAl I Di rectori es, ni I ); 
for strPath in pathList do 
begi n 

filesList := TDi r ec t o r y . Ge t F i I es (strPath, '*.pas')\ 
for strFile in filesList do 
sFi I esLi st , Ad d ( strFile); 

end; 

// now copy the file names only (no path) to a list box 
for strFile in sFilesList do 

Li stBoxl. I t ems . Add ( TPat h. Get F i I e N a me ( s t r F i I e) ) ; 

end; 
end; 

In the final lines, theGet Fi I eName function of TPat h is used to extract the file 
name from the full path of the file. This is equivalent to using the good old 
Ex t r a c t F i I e N a me global function. TheTPa t h record has a few other interest- 
ing methods, which go beyond what was already avail able in Delphi, including 
aGetTempFi I eName,aGet RandomFi I eName,a method for mergi ng paths, a 
few to check if they are valid or contain illegal characters, and much more. 
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Filtering Sub-folders 

There are two problems with the two methods above. First, they have very lim- 
ited filtering capabilities. When you browse folders for a Delphi file, you'll 
bumpintojii story folders created for backing up thesourcecode files or 
sub-folders used by version control systems, which generally start with a 
period. Also, you can search for one file extension, but not for two at the same 
time. A second problem isthat a search into many sub-folders can be quite 
slow, so you might want to think of spawning a separate thread to keep the user 
i nterface responsive (and provide some cl ue about the progress). 

Usi ng a thread can be a good idea, but both issues can also be fixed usi ng an 

anonymous method of typeT Fi I terPredi c at e 36 . This version of the 

btnSubfol dersCI i ck method solves the first problem: 

procedure TForml oFi I es. btnFi I terFol dersCI i ck( Sender: TObject); 
va r 

pathList: TStri ngDynArray; 
strPath: string; 
begi n 

pathList := T Di r e c t o r y . Ge t Di r e c t o r i e s ( ed Ba s e F o I d e r . Te x t , 
TSearchOpti on, soAl I Di rectori es, 
function (const Path: string; 

const SearchRec: TSearchRec): Boolean 
begi n 

Result : = not (SearchRec. N a me = '__/?/ story') and 
not (SearchRec. Na me [1] = '.'); 

end) ; 

for strPath in pathList do 
Li st Boxl. I t ems. Add (strPath); 

end; 

The final version differs only in the anonymous method and addresses both 
issues: 

pathList := T Di r e c t o r y . Ge t Di r e c t o r i e s ( ed Ba s e F o I d e r . Te x t , 
TSearchOpti on, soAl I Di rectori es, 
function (const Path: string; 

const SearchRec: TSearchRec): Boolean 
begi n 

Result : = not (SearchRec. Na me = '__/)/ story') and 

not (SearchRec. Na me [1] = '.'); 
I nc ( n T o t a I ) ; 
if Resul t then 

I nc ( nFound) ; 



36 If you don't I ike the embedded anonymous methods definition syntax, you can createa 
separate fundi on and pass it as a parameter, although this partially defeats the notion of 
using anonymous methods (that is, their ability to capture the execution context). 
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StatusBarl.Si mp I e T e x t : = For ma t ( 

1 Fol ders %d/%d' , [ nFound, nTotal ] ) ; 
Appl i cat i on. Process Me s s a ges ; 
end) ; 



Filtering Files 

In a very similar fashion, we can write a filter looking for both Pascal source 

codefiles(. pas ) and Delphi project files (. dpr ). At the core of the new 

method, which agai n parses folders removi ng _ _ h i story and folders starti ng 

with a period, there is thefollowing Get F i I es call with a filter predicate: 

filesList : = TDi rectory. GetFi I es (strPath, 
function (const Path: string; 

const SearchRec: TSearchRec): Boolean 
va r 

strExt: string; 
begi n 

strExt : = TPath. GetExtensi on(SearchRec. Name) ; 
Result := (strExt = '.pas') or (strExt = '.dpr'); 
Inc (nTotal); 
if Resul t then 
Inc (nFound) ; 
StatusBarl. Si mpl eText : = For ma t ( 
' Fi I es %d/ %d' , nFound, nTotal ] ) ; 
Appl i cati on. Process Me s s a ges ; 
end) ; 

The three record structures i n the I OUti Is unit have many more features than 
I 've covered and are certainly worth a second look. File operations in Delphi 
used to below level, unless you used a third- party library. In Delphi 2009, the 
development team fixed text file manipulation with thenewTSt r e a mRe a d e r 
andTSt r ea mWr i t er classes, now in Delphi 2010 there is also a higher level 
approach for manipulating folders, paths, file names and properties. 



What's Next 



Over the last two chapters I focused on new features of the compiler and the 
RTL, the core foundations of all Delphi applications. Most programs written 
with Delphi, however, also have a user interface built using the VCL and inter- 
act with the operating system. I n the next three chapters I 'II focus on new VCL 
features and on the support for the I atest versi on of the OS, Wi ndows 7. 
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Chapter 5: The 

VCL And 
Windows 7 



If Delphi's Run Time Library lets you perform some basic operations, it is the 
Visual Component Library (VCL) that provides the core interaction with the 
Wi ndows operati ng system and lets you create the user i nterface of your pro- 
grams. I n Delphi 2010 the VCL was updated to support the latest version of the 
operating system, Windows 7. 

I n this chapter I 'II explore new features of Wi ndows 7, the avai lable support i n 
the VCL, and other new VCL extensions. I'll also show you how to program 
against Windows 7 in areas for which the VCL has no explicit support. 
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Tech Overview of Windows 7 

A lot can be said about Windows 7 and I certainly have no room for a full evalu- 
ation of this new operating system. My aim in this short section is only to give 
you some technical information about changes compared to Windows Vista. 

For of all, notice that the version of the operati ng system is not 7 (as you might 
expect) but 6.1 Thiscan be easily verified by using the Del phi global variables 

Wi n 3 2 Ma j o r Ver s i on and Wi n 3 2 Mi no r Ver s i on. 

If you need to check if the version of Windows your program is running onto is 
at least Windows Vista or Windows 7, you can usetheChec k Wi n 3 2 Ver s i on 
function as follows 37 : 

i f CheckWi n 3 2 Ve r s i on( 6) t hen 

Log ('Running at least on Vista'); 
if CheckWi n32Versi on( 6, 1) then 

Log ( ' Runni ng on V ) ; 

Beside many i improvements, in terms of a reduced memory footpri nt and a 
more functional user interface, Windows 7 has a significant number of new 
API 38 functions. 1 1 is relevant to notice that these new API s come i n two forms: 
C- language functions and COM interfaces. That is, the Windows API is being 
extended in a very traditional way, that doesn't require programming to be with 
.NET. On the contrary, Delphi offers complete support for all of the new fea- 
tures of the operati ng system. 

To a very large extent, Windows 7 is very similar to Windows Vista, having the 
same driver model, the same User Account Control and Windows Resource 
Protection mechanism, the same desktop windows management, the same 
Glass theme activated by default, and much more. Still, there are areas in which 
there are distinct differences, from the behavior of Taskbar buttons to the 
introduction of Libraries, from an extended version of DirectX to new graphical 



37 This code is part of theGetOSVersion example, updated from the original version of the 
demo in my Delphi 2007 Handbook. 

38 The Windows API , or Application Programming Interface, is the col lection of all of the 
functions of the operating system that an application can call. The Windows API is huge 
and offers countless operations, built around the three libraries that still constitute the 
core of the operating system (from the Windows 10 days), Kernel, User and GDI . The 
Windows API is fully documented intheSDK help that ships with Delphi and isalsoon 
theMSDN website, http://msdn.microsoft.com/en-us/library/default.aspx. 
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processing components, from gestures and touch support to an inertia pro- 
cessor, from a sensors platform to federated search support. 

Whilesomeof these new features are well integrated into the VCL in Delphi 
2010, others require using theAPI directly, something that should nOt cause 
any great problem to Delphi developers. I'll delve into some of these new fea- 
tures of the operati ng system throughout this chapter and the next. 

1 1 might be worth starti ng by providi ng a summary of the support already avai I- 
ablefor Vista (and hence also for Windows 7, for those migrating to it directly 
from Windows XP) in the last two versions of Delphi. Details of these features 
were covered in my two most recent Delphi Handbooks. 

Delphi Support for Windows Vista 

Starting with Delphi 2007, the Delphi R&D team has been putting considerable 
effort into supporting new versions of the operating system in the VCL. This is 
a change from the past, as in the name of compatibility with older versions of 
the operati ng system, Delphi 2006 still didn't provide explicit support for many 
features of Wi ndows X P I i ke new control styl es. 

N eedl ess to say that i n some cases taki ng advantage of new features of Vi sta 
might mean that your application will not run as expected on Windows XP or 
Windows 2000 39 . Here is a very condensed summary of recent Delphi features 
specifi cally focused on supporti ng Wi ndows Vista: 

• The De f a u I t F o n t property of theA p plication object has been added to 

si mpl ify the support for the new system font, Segoe U I , i n Vista applications. 
Thisfont is used by default by all forms of your application (if their 
P a r e n t F o n t property is set to True) . There is also a si mi lar Me s s a g e F o n t 
property i n the Screen Global object, used for the font of some of the mes- 
sage dialogs. 

• In Windows Vista traditional Delphi applications had problems displaying 
the preview of minimized application in the Windows Flip (orTaskbar pre- 
views), Windows Flip 3D, and theAlt-Tab window. To overcome this issue, 
theA p p I i c a t i on object has a new Mai nFont OnTas kbar property that 
enables the display of the main form, rather than the application hidden 



39 Support for Windows 95 and 98 at target platforms for Delphi applications was dropped 
in Delphi 2009, with the advent of Unicode. Platforms with verylimited Unicode support 
couldn't be supported any more. 
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window, in theTaskbar. As I 'II discuss in the next section, this is no longer 
needed in Windows 7. 

• Forms have a new G I a s s F r a me property that let's you easi ly extend the 

gl ass frame of wi ndows i nto thei r cl ient area. M any components have been 
extended to support bei ng pai nted over the gl ass surface, although you 
might have to enable their Do u b I eBuffered property to get correct output. 

• Vista Task dialogs aresupported by Delphi in two different ways. There is a 
new specific TaskDialog component, with extended features, and asimple 
TaskMessageDI g function that gets automatically called in placeof 

Me s s ageDI g when you settheglobal Us e L a t es t Common Di a I ogs to True. 

• The new Vista Open and Savedialog boxes (implemented by the 

I Fi I eOpenDi al og and I Fi I eSaveDi al og interfaces) are directly mapped 
by the new FileOpenDialog and FileSaveDialog components, but also the 
standard OpenDialog and SaveDialog component uses the new style when 
the global Us e L a t es t Co mmo n Di a I ogs is set. 

• Themes can now be enabled through a project options setting, which also 
activates them at design ti me. Themes are more relevant than i n the past 
and many new user interface features in Vista (and Windows 7) are avail able 
onlytothemed applications. 

• The new TreeView style with small triangles replacing the pi us and minus 
symbols isenabled by default in the VCL. 

• Button controls have been enhanced with support for the command link and 
split button styles. 

• Label controls support the glowing style when painted on a glass surface. 

• Several styles already avail able si nee Windows XP but not part of the VCL 
for a long ti me have recently been i implemented. These new VCL features 
include extensions to edit boxes (text hints, numbers filtering, and align- 
ments), grouping support for the ListView control, and RichEdit version 2 
support. 

• Progress bars have been extended to support the newest options, i ncl udi ng 
status information (affecting the progress bar color), smooth movements, 
and smooth reverse movements. Some of these features were al ready i n 
Windows XP, while others are specific to Vista. 

• Shell Resources is a new Delphi component that helps you overcome the lack 
of the standard system ani mations i n Vista and beyond. I f you are usi ng an 
Animate common control with the standard ani mations that were available 

i n older versions of Wi ndows, your program won't work any more as those 
animations are no longer part of the operating system. As an easy fix, add 
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this component anywhere in your program (or simply include its unit) to 
compile resources corresponding to the animations that used to be in the 
operating system into your own application. 

As you can see from this list, which is far from complete and detailed, recent 
versions of Delphi provide a significant amount of support for new features of 
the recent versions of the Wi ndows operati ng system. This has been a signific- 
ant change as i n the past backward compati bi I ity with Wi ndows 9x has I i mited 
the support for si milar extensions. 

Delphi 2010 pushes this support one step forward, with new specific compon- 
ents, new API declarations (also thanks to delayed loading 40 ), and the Object 
Pascal version of many new COM interfaces. Before delving into this topic, 
however, let me focus on changes between Vista and Windows 7 that affect 
some of the features discussed earlier and covered in my previous books. 

Notable Differences Between Vista and 
Windows 7 

H avi ng covered i n summary new features of recent version of Del phi that let 
you better support Windows Vista and Windows 7, 1 have to underline the fact 
that Windows 7 adds a few extra features that makeexisting/ old Delphi 
appl i cati ons more compati bl e wi th the new operati ng system. There are a 
couple of these differences worth mentioni ng. 

The first relates with the preview of the application main form available in 
Windows Flip (the task bar preview), Windows Flip 3D, or even the plain list of 
windows you obtain using Alt+Tab keys. In Vista, a traditional Delphi applica- 
tion would have been represented by its icon when it was minimized and 
di spl ayed i n any of these vi ews 41 . 

The fix came to the VCL in Delphi 2007 with the Ma i n F o r mOn T a s k b a r prop- 
erty of theT Appl i cati on class. In Windows 7, however, a traditional Delphi 
application would show properly in the various previews, even when minim- 
ized. This basically means that the Mai nfor mOnTas kbar property becomes 



40 Delayed loading of DLL functions was covered in Chapter 4. 

41 This feature of Vista and theproblems it poses, alongwith possible solutions is discussed 
in details in my Delphi 2007 Handbook. The same is true for the Windows Resource Pro- 
tection problems covered next. 
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much I ess relevant, although it will still affect the title displayed for the applica- 
tion in thetaskbar. With older versions of Delphi, or in case the property is set 
to False, the title will match theTi tl e property of theAppI i cati on global 
object; on the other hand, if Ma i nFor mOnTas kbar is set to True, the title is the 
C a p t i on of the mai n form. 

Another relevant change relates to the behavior of Windows Resource Protec- 
tion and the Vi rtual Storage (the area created for each user to host thei r 
document and configuration files that old "non-themed" applications save in 
Program Files sub-folders or in the Windows folder). Windows 7 expands the 
vi rtual storage area to i ncl ude the root of the C : drive 42 . 

As an example, the FileAccess program discussed in my "Delphi 2007Hand- 
book" tri ed to save a f i I e to the root of the C : dri ve wi th the code: 

procedure TFormFi I e. btnSaveRootCI i ck( Sender : TObject); 
begi n 

Memol. Li nes . SaveToFi I e ( ' C: I So me Text . txt'); 
end; 

I n Vista this code used to fai I with an error both for a themed and a non- 
themed application, in Windows 7 the themed application succeeds and saves 
the file to the basic folder of the virtual store area, which on my computer (for 
my account) is: 

| C: \ User s\ Marc o\ Ap p Da t a\ Local \Vi rtual Store 

The full source code of the program isavailablein the FileAccess folder. Notice 
there are two similar applications, compiled with and without a manifest (that 
is, themed or non-themed). 

By the way, compared to the version written for Delphi 2007, 1 had to update 
theRunAs Admi n procedure I originally borrowed from Fredrik Haglund, to 
support widestrings and thecall of the 'wide' version of Shel I ExecuteEx. 

This is the code used to ask for elevation of the child process: 

procedure RunAsAdml n( hWnd: HWND; a F i I e : string; 

aParameters: string); 
va r 

sel: TShel I Executel nfo; 
begi n 

Fi I I Char( sel , Si zeOf ( sei ) , 0) ; 
sei.cbSize := sizeof(sei); 



42 I 've noticed that in same circumstances this helps BDE applications to behave better on 
Windows 7 than on Windows Vista, but you still have to redefine the NET dir and... get 
rid of the BDE as soon as you can! J ust a personal opinion, of course. 
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s e i . Wn d : = h Wn d ; 

sei.fMask := SEE MASK FLAG DDEWAIT or 

S E E_ MAS K_ F L AG_ N0_ Ul 7 
s ei . I pVer b : = ' runas ' ; 
sei.lpFile : = PChar(aFile); 
sei . I pParameters : = P C h a r ( a P a r a me t e r s ) ; 
sei . nShow : = SW_ S HOWNORMAL ; 

if not Shel I ExecuteEx(@sei ) then 
R a i s e La s t OS Er r o r ; 

end; 



Delphi 2010 Windows API Units 

As I mentioned earlier, Delphi 2010 piggy backs on the support available in 
Delphi 2009 for Windows Vista, completing it with specific extra features. 
Before getti ng to new VCL components supporti ng Wi ndows 7, it is worth look- 
ing at the first level of the Windows SDK support, that is Windows API import 
units and COM interface declarations. 

Beside brand new units, there are also quite a few that have been extended in 
significant ways, with the incl usion of many new API s or COM i nterfaces. 

New API Header Units 

Several new RTL units have been added to Delphi 2010 to provide the Pascal 
I anguage transl ati on of the header f i I es of new I i brari es of the Wi ndows SD K . 
These new libraries include DirectX support and several others. 

Although I don't have room to delve into them in detail, here is a partial list of 
the new API header units, parti ally coming from third parties (and available 
with theMPL open-source license) and partially introduced bythe Delphi R&D 
team for the new version of the product: 

• There are new headers for interfacing .NET from unmanaged code, spe- 
cifically hooking into mscoreedll. These are provided in the Cor unit, along 
with two support units, CorError and CorHdr. 
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• DirectX support headers developed by Project J EDI 43 are now included in 
the core Windows units, comprising: 

Direct3D Direct3D8 Direct3D9 

DirectDraw Directlnput DirectMusic 

DirectPlay8 DirectSetup DirectShow9 

DirectSound DxDiag DXFile 

DXTypes DX7toDX8 D3DX8 

D3DX9 

• Other DirectX header types, related with technologies introduced in 
Windows Vista and Windows 7 and partially wrapped by the VCL are avail- 
able the foil owing new units: 

D2D\ core elements for Direct2D support, some of which are covered 
later in the section "Direct2D". 

Dxgi Format, headers for the core DirectX Graphics I nfrastructure 44 . 

WMF9, Windows Media Format 9 API (conversion provided by Henri 
Gourvest). 

Manipulations, hosts the interface for the inertia manipulation 
engi ne of Wi ndows 7, used for movi ng thi ngs around your screen i n a 
more realistic way (there is an example of the use of the mani pulation 
and the i nerti a processors i n the next chapter) . 

Wincodec provides headers for interfacingwindowscodecs.dll and is 
used to enable support for TWI CI mage, covered later i n this chapter i n 
the section "Using Windows I maging Component". 

• Thedefinition of thel Obj ect Ar r ay and I Obj ectCol I ecti on interfaces 
(used among others by some of the Shel I APIs) is now available in the new 
ObjectArray unit. 



43 TheJ oint Endeavour of Delphi Innovators (Project J EDI, http://www.delphi-jedi.org) is 
one of the most well known and active Delphi open source initiatives, which started off 
by translating API headers not found in the product. Offering access to the DirectX API 
was part of this task. Most of the work on the DirectX headers has been done by Alexey 
Barkovoy, but other contributors are listed in the units themselves. 

44 See among other sources http://en.wiki pedia.org/wiki/DirectX_Graphics_ I nfrastruc- 
ture and http:// msdn.microsoft.com/ en- us/ 1 i brary/ bb205075(VS.85) .aspx 
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• Windows Search 45 support is provided by the interfaces to the structured 
query interfaces located in the units StructuredQuery and StructuredQuery- 
Condition. 

• Thereareother new headers for tablet support, includingTpcShrd, 
RtsCom, and Msl nkAut. 



Extended Windows API Headers 

Some of the existing library files, starting with the base Windows unit, have 
also been augmented with new functions. Some of these API functions were 
si mply missi ng, whi le others were operati ng- system version dependent, and 
have now been i implemented usi ng the new del a y e d di recti ve 46 . 

Some noteworthy additions to Wi ndows unit i ncl ude API s that have been 
around for sometime, but were not previously available in the core Delphi 
i nterface unit for the Wi ndows API : 

function Get LongPat hNamef I psz Shor t Pa t h : PWideChar; 

I pszLongPat h: PWideChar; cchBuffer: DWORD): DWORD; stdcall; 
function Ge t P r oc es s Ha nd I eCo un t ( hP r oc es s : THandle; 

var pdwHandl eCount : DWORD): BOOL; stdcall; 
function GetProcessI d( Process: THandle): DWORD; stdcall; 
function Ge t Co mpu t e r Na me E x ( Na meTy pe : TCo mp u t e r Na me F o r ma t ; 

IpBuffer: PWideChar; var nSize: DWORD): BOOL; stdcall; 

Two i nteresti ng new functions ( part of the SDK si nee a service pack of Wi n- 
dowsXP) areSet DI I Di rectory and Get DI I Di rectory, which you can use to 
determine and change the folder from which an application will load its 
dynamic libraries and Delphi run-time packages. 

There are about new 10 "timer queue" support functions, starting with: 

|function CreateTi merQueue: THandle; stdcall; 

There are also various touch input support functions and data structures, ges- 
ture support, devices integration, physical points support and the like. 



45 For a reference to the Wi ndows Search SDK you can refer to 
http:// msdn.microsoft.com/ en-us/ 1 i brary/ aa965362(VS.85) .aspx 

46 Delayed functions are used to avoid the standard DLL load time binding, which might 
prevent an application to run on an alder version of the operating system even for a 
single extra API call. This was described inthe section "Delayed Loading of DLL Func- 
tions" of Chapter 4. 
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M ost of the API functions that are specific to Wi ndows Vista or Wi ndows 7 are 

declared as delayed, including: 

// Vista desktop management 
CreateDesktopEx 
GetlconlnfoEx 
SetProcessDPI Awa r e 

// Vista logical cursors 

GetPhysi cal CursorPos and SetPhysi cal CursorPos 
Logi cal ToPhysi cal Poi nt and Physi cal ToLogi cal Poi nt 
Wi ndowFromPhysi cal Pol nt 

/ / Vista power management 

Regl sterPowerSetti ngNotl f i catl on 

Unregl sterPowerSetti ngNoti fi cati on 

/ / Vista clipboard notifications 
AddCI i pboardFormatLi stener 
Removed i pboardFormatLi stener 
GetlipdatedCI i pboardFormats 

// Windows 7 display management 
Cal c u I atePopupWi ndowPosi ti on 

GetWi ndowDi spl ayAffi ni ty and SetWi ndowDi spl ayAffi ni ty 

// Wi ndows 7 touch support 

Get Touc hi nput I nf o 

I sTouchWi ndow 

CI oseTouchl nput Handl e 

Regi sterTouchWi ndow and Unregi sterTouchWi ndow 

// Windows 7 gestures support 

Get Ge s t u r e I nf o and CI oseGesturel nfoHandl e 

Get Gest ureExt raArgs 

Set Gest ur eConf i g and Get Ges t ur eConf i g 

The companion Messages unit has the definition for new messages (includ- 
ingwm_ Gesture, wm_ To uc h , wm_ CI i pboardUpdate, and afewwm_ X B u 1 1 o n 
ones) and their related data structures. 

TheDwmApi unit has been largely extended and rewritten using delayed 
loading rather than custom dynamic loading. There are also some new func- 
tions added for Wi ndows 7. This unit i nterfaces the Desktop Wi ndows 
Manager 47 library first introduced in Vista. 

TheShlObj unit has been largely extended, providing the definition of dozens 
of new i nterfaces, some of which were al ready part of previous versions of Wi n- 



47 See http:// msdn.microsoft.com/ en-us/ 1 i brary/ aa969540.aspx for a detai led introduc- 
tion to the Desktop Windows Manager API . 
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dows, whileothers have been added for Windows Vista and Windows 7. The 
latter include thel T a s k b a r and thel Shel I Li brary interfaces I'll demon- 
strate later in this chapter in the section "Working with Taskbar Buttons in 
Windows 7". To have an idea of how many more interfaces are covered, con- 
sider this unit has grown from 4,000 lines to over 14,000 lines (or from 185 Kb 
of source code to over 667 Kb). Also the Shel I API unit sees a significant revi- 
sion, incorporating new and missing API functions and interfaces. 

TheWinSpool unit (hosting the Win32 printer API Interface) isnow almost 
twice as large and supports many newer capabilities of the operating system. 

Finally, the mxsm I unit has extended support for version 6 of the Microsoft 
XML DOM engine. I'll cover the changes in XML support in Delphi 2010 in 
Chapter 8. 



Windows 7 Support 

Having looked at a rather long list of changes in terms of low-level API support, 
it is worth consideri ng which new features of Wi ndows 7 we can program 
against using some of these new APIs. Later I'll move to features specifically 
supported by the VCL, with ready- to- use components, including the Direct2D 
support and more. 

Two of the new features of Wi ndows 7 that are most vi si bl e to users are the 
changes to taskbar buttons (which can provide status information about the 
running application and direct commands to interact with it) and the introduc- 
tion of libraries (a new way to collect and manage files and folders). 

Working with Taskbar Buttons in Windows 7 

One of the most noticeable new features of the Wi ndows 7 user i nterface is the 
new role of taskbar buttons, the graphic generally positioned at the bottom of 
the screen and showing the various applications that are currently running. I n 
Windows 7 you can mix running applications with regularly used ones: You pin 
a program to the taskbar and its icon will remain there even when the applica- 
tion is not running. 
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These new taskbar buttons provide several ways to interact with an application. 
When the program is closed, you can see recent documents opened with it and 
see a menu with custom operations. When the program is running you can see 
a preview of its main windows (fully customizable), see status information, add 
extra buttons and commands, seethe progress of a slow operation, and much 
more. I wi 1 1 not explore al I of the features of taskbar buttons i n Wi ndows 7 
here, while building an examplecalled Win7Taskbar. I'll cover only the most 
common taskbar features 48 , while showing you how to use the related COM 
interfaces, which are part of the Windows Shell API. 

The TaskList I nterfaces 

TheShlObj unit in Delphi 2010 defi nes the i nterfaces you can use to interact 

with the taskbar elements. There are actually four of these i nterfaces, each 

extending the previous one: 

I TaskbarLi st = i nt erf a c e ( I Unknown) 
I Taskbar Li s 1 2 = i nt e r f a c e ( I Ta s k b a r L i s t ) 
I TaskbarLi st3 = i nterface( ITaskbarLi st2) 
I TaskbarLi st4 = i nterface( ITaskbarLi st3) 

What you can do is to ask the system for an object i mplementi ng taskbar sup- 
port and extract the various interfaces from it. As a helper you can use across 
projects, I 've defined the foil owing data structure: 
type 

TTaskBarSupport = class 
public 

TaskbarLi st: ITaskbarLi st; 

TaskbarLi s 1 2 : I TaskbarLi st2; 

Tas kba r Li s 1 3 : I Ta s k ba r L i s 1 3 ; 
publ i c 

constructor Create; 

procedure I ni tTaskbarSupport; 
end; 

The core of th i s cl ass i s i n the method that creates the f i rst COM obj ects and 

extracts its various i nterfaces 49 : 

procedure TTaskBarSupport. I ni tTaskbarSupport; 
begi n 

TaskbarLi st := Cr eat eComObj ect ( CLSI D_ T a s kbar Li st ) 
as I Tas kbar Li st ; 



48 For more examples and Delphi components you can use to simplify your interaction with 
the Windows 7 taskbar (also using older versions of Delphi) see Daniel Wischnewski blog 
on www.gumpi.com and (in particular) the post: http://www.gumpi.com/Blog/2009/ 
09/27/ Del phiControlsForWindows7StateUpdate.aspx 
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Tas kbar Li st . Hr I ni t ; 

Supports(TaskbarLi st, I I D_ I Ta s k b a r L i s 1 2 , Tas kbar Li st 2) ; 
S u p po r t s ( Ta s k ba r L i s t , I I D_ ITaskbarLi st3, Tas kbar Li st 3) ; 
end; 

TheTaskbarSupportUnit unit that defines this data structure creates a global 
instance of the class (called Tas kBarSupport)in its initialization section, so it 
can be used directly within any program that includes the unit. 



A Progress in the Taskbar 



N ow that we have a way to access to the taskbar i nterfaces, we can 
start i mplementi ng one of the new Wi ndows 7 taskbar features, 




namely thedispl ay of progress bar information within ataskbar 
button, as you can see here on the right. This display is enabled by calling the 
I TaskbarLi s 1 3 . SetProgressState method, while the actual progress is set 
by calling I TaskbarLi s 1 3 . Set Pr og r es s Va I lie . At the end you have to 
restore the progress state of the taskbar button to normal . 

To make the user interface more intuitive, I've also added a ProgressBar com- 
ponent to the main form, moving it in sync with the taskbar button: 

procedure TWi n 7 T a s kF o r m. bt n Pr ogr es s CI i c k( Sender : TObject); 
var 

I : Integer; 
FormHandl e: THandle; 
begi n 

FormHandl e := Get Tas k B a r Ent r yHandl e; 
TaskbarSupport, TaskbarLi s 1 3 . SetProgressStatef 

For mHandl e, TBPF NORMAL) ; 
for I ; = 1 to 100 do 
begi n 

ProgressBar 1. Position := I; 

TaskbarSupport. TaskbarLi s 1 3 . SetProgressVal ue( 

For mHandl e, I, 100); 
Appl i cat i on. P r o c es s Mes s a g es ; 
SI eep ( 100) ; 
end; 

TaskbarSupport. TaskbarLi s 1 3 . SetProgressStatef 
For mHandl e, T B P F _ NOP ROGRE S S ) ; 

end; 



49 N otice that the class I D of theCOM objectyou passtotheCr eat eComObj ect function 
(in thiscaseCL S I D_ TaskbarLi st) matches the i nterface I D of the interface the object 
implements (in this case I I D_ I TaskbarLi s t ). I find this approach confusing, as it 
doesn't follow standard COM development guidelines, but you can easily get used to it. 
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N oti ce that each of the cal Is requi res the handle of the form vi si bl e i n the 

taskbar. This can be either the main form or the application hidden form, 

depending on the VCL configuration: 

function GetTaskBarEntryHandl e: THandle; 
begi n 

if not Application. Ma inFormOnTaskBar then 

Result : = Application. Handle 
else 

Result := Ap p I i c a t i o n , Ma i n F o r m. Ha n d I e ; 

end; 

When trying this feature notice that if the application is not active, the progress 
bar in the taskbar icon will have a more contrasted color... and be more visible. 

Overlay I cons 

A second taskbar button feature you can work j ^ j A fSk I iT , jt>» j 
with is overlay icons. These are small icons you 
can add on top of the icon in the taskbar button 

(that is the form icon, by default). Hereon the right you can see the original 

icon and a couple of overlay elements. These elements, in my demo program, 

are extracted from an I mageList using the following code: 

procedure TWi n7TaskForm. btnOverl ayl conCI i c k ( 

Sender : TObj ect ) ; 
va r 

anlcon: Tlcon; 
begi n 

anlcon : = Tlcon. Create; 
try 

I mageLi stl. Getl con( Random( 3) , anlcon); 
TaskbarSupport. TaskbarLi s 1 3. SetOverl ayl con( 
GetTaskBarEntryHandl e, anl con. Handl e, 
PCharf ' Myl con 1 ) ) ; 
finally 

anl con. Free; 
end; 
end; 

The I TaskbarLi s 1 3. SetOverl ayl con method requi res the form handle, the 
handleof the icon, and a description for accessibility purposes as parameters. 
To remove the current overlay icon, pass 0 for the icon handle, as the program 
does in the bt nNoOverl ayCI i ck method. 



Marco Cantu, Delphi 2010 Handbook 



Chapter 5: TheVCL and Windows 7- 139 

Task Buttons 

The last feature I want to demonstrate i n the Wi nTTaskbar example is the sup- 
port for task buttons. These are smal I buttons that get displayed along with the 
miniature of the application's main form as you move the mouseover the 
taskbar entry. You can associate code with the click event on those buttons, by 
handling thewmSy s Command message. Before I get to the code of the program, 
though, it is worth showi ng you a picture of task buttons. 



Below you can seea regular version of the miniature view of the demo program 
compared to a version with three task buttons activated: 




Now that you have seen what the user i nterface for taskbar buttons looks like, 

we can see how to activate it in your Delphi code. What you have to do is create 

an array ofTThumbBut t on elements, give each of them an id, the number of an 

element from an I mageList, set a few masks and flags, and provide a hi nt. At 

the end you'll pass th i s array (technical I y the address of its first element) as 

parameter to the I TaskbarLi s 1 3 . Thumb BarAddButtons method after 

assigning the I mageList to the taskbar button: 

procedure TWi n7TaskForm. btnTaskButtonsCI i ck(Sender: TObject); 
var 

Buttons: array of TThumb Button; 
I : Integer; 
begi n 

Set Lengt h( But t ons , 3) ; 
fori : = 0 t o 2 do 
begi n 

But t ons [ I ] . i I d : = I ; 

B u 1 1 o n s [ I ] . i B i t ma p : = I ; 

Buttons! I ]. dwMask := T H B FLAGS or THB BITMAP or THB TOOLTIP; 
But t ons [ I ] . dwFI ags := THBF ENABLED or" 
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THBF_ NOBACKGROUND or THBF DI SMI S50NCLI CK; 
StrCopy ( Buttons! I ] . szTi p, 

PChar ( 1 but t on 1 + I nt ToSt r ( I ) ) ) ; 

end; 

TaskbarSupport. TaskbarLi s 1 3 . Thumb BarSetl mageLi s t ( 
GetTaskBarEnt ryHandl e, I mageLi stl. Handl e); 

TaskbarSupport. TaskbarLi s 1 3 . ThumbBarAddButtonsf 

GetTaskBarEnt ryHandl e, Lengt h( But t ons ) , @B u 1 1 ons [ 0] ) ; 



Working with Libraries 



Another specific new feature of Windows 7 is the definition of libraries. These 
are col lections of fi les and folders groups under a custom name and easier to 
reach even if they reside in different areas of your hard drive, external drive, 
network drive, and so on. 

I don't want to delve into the behavior of libraries in Windows 7 here or the 
reason for using them (although I have to say that I I ike the idea a lot), but 
focus on how you can interact with the libraries from a Delphi application. The 
two most relevant interfaces to use, both declared in theShlObj unit, are 
I Shel I Li brary and I S h e I I I t e m. You might also want to use some of the 
default folder constants declared in the KnownFolders unit. 

Before looking at these interfaces, though, lets look at how libraries appear in a 
classic OpenDialog and a new FileOpenDialog. To demonstrate this the 
Win7Libraries example has both components and 
two buttons to acti ve them. I n case of the tradi - 
tional dialog box, the program disables the 
UseLat est CommonDi a I og global variabletodis- 
ablethe automatic redirection of the old common 
dialog box to the newer version. 

I n the cl assi c Open D i al og, I i brari es are j ust a si de 
icon, as you can see here on the right. I n the 
newer FileOpenDialog, instead, the navigational 
tree i ncl udes I i brari es and the abi lity to expand 
thei r detai Is, as you can see i n the next i mage. 



Open 



Look in: [j] Documents 



a . 

Recent Places 



Deslctop 



Libraries 



Name 

Downloads 
ERStudioS.OI 
Gom Player 
Integration 5 
Integration 5 
RAD Studio 
RAD Studio 
I , SQL Server I* 
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Open 


► Libraries ► Documents ► 


Organize New folder 


^ Recent Places 
^ Libraries 




Documents library 

Includes: 2 locations 

_ 


[Hi Document: 




Name 


" My Documents- 
Public Documents 
Marco 


P Downloads 
i_ t ERStudioS.ODE 
GomPlayer 



There are several ways to interact with libraries and their information. First of 
all, you can query the system for the file defining the library: 

va r 

pc h : PCha r ; 
begi n 

01 eChec k( SHGet KnownFol d e r Pat h ( 

F 0L DERI D DocumentsLi brary, 0, 0, pch)); 
Memol. Li nes . Ad d ( ' SHGet KnownFol derPat h: ' + pch); 

I n thi s case the name of the f i I e physi cal I y hosti ng the I i brary i nfor mati on , 

returned by the code snippet above, would be: 

SHGet KnownFol derPath: C:\Users\Marco\AppData\Roami n g \ M i crosoft\ 
Wi n d o ws \ Li brari es\Documents. I i brary - ms 

I f you want to access to more detai I s of the gi ven I i brary, you can use the 
SHGet KnownFol derl t em function, which fills a pointer with an I Sh el I I t em 
interface: 
va r 

item: I S h e I I I t e m; 
pch: PCha r ; 
pnt : Pointer; 
begi n 

01 eChec k( SHGet KnownFol derl t e m( 

FOLDERI D_Document sLi brary, 0, 0, I S h e I I I tern, pnt)); 
item : = I Shel I I t em (pnt); 

i tern. GetDi spl a y Na me ( SI GDN_ NORMAL Dl SPLAY, pch) ; 

Memol, Li nes. A d d ( ' SHGet KnownFol der 1 1 em. Get Di s pi ay Na me : ' + pch); 

The output i n this case would be: 

| SHGet KnownFol derl tern. GetDi spl ay Name: Documents 

To access the actual library and manipulate it, we need to perform a further 
step and ask the system for a COM object i mplementi ng the I Shel I Li brary 
interface that we'll later initialize with the proper I Shel I I temelement: 
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var 

aLibrary: I Shel I Li brary; 
Obj : I I n t e r f a c e ; 
item: I Shel I I t em; 
pc h : PCha r ; 
pnt : Pointer; 
begi n 

01 eChec k( SHGet KnownFol der I t em( 

FOLDERI D_ Do c u me n t s L i brary, 0, 0, I Shel I I t e m, pnt)); 
item : = I Shel I I t em (pnt); 

aLibrary := Creat eCo mO bj ect(CLSI D_Shel I Li brary) as I Shel I Li br ar y; 
aLi brary. LoadLi braryFroml tem(i tern, PropSys. GPS_READWRI ; 

Nowthat we have the library interface tied to the I Shel I I t em for the given 
folder, we can use it, for example to extract the list of elements it contains: 

var 

anArray: I Obj ectArray; 
nltems: Cardinal; 
I : Integer; 
begi n 

aLi brary. GetFol ders( LFF_FORCEFI LESYSTEM, I Ob j e c t Ar r a y , anArray) ; 
anArray. Get Count (nltems); 
for I : = 0 to nltems - 1 do 
begi n 

a n Ar r a y . Ge t At ( I , I Shel I I t e m, item); 
i tern. GetDi spl a y N a me ( SI GDN_ NORMAL Dl SPLAY, pch) ; 
Me mol, Li nes . Ad d ( ' Li brary item: ' + pch); 
end; 

I n the specific case this produces the list of the folders in library: 

IL i b r a r y item: My Do c u me n t s 
Library item: Public Documents 

Other operations you can accomplish on a library include adding and removing 
folders, getti ng and changi ng the default save folder for the I i brary, readi ng and 
changing the folder type (music, documents, and the I ike), and extracting or 
changi ng the I i brary i con . 

The demo program has a further feature it might be worth exploring. It let's 

you open and display the XML file that defines the library, using this code: 

procedure TFor ml, btnLi braryXml CI i ck( Sender : TObject); 
var 

pch: PChar; 
begi n 

01 eChec k( SHGet KnownFol der Pat h ( 

FOLDERI D_ Do c u me n t s L i brary, 0, 0, pch)); 
Memol. Li nes. LoadFromFi I e ( pch) ; 
end; 
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The result issomething I ike the following, not exactly a readable description 

even if it uses the XM L format: 

<? x ml versi on=" 1. 0" encodi ng=" UTF - 8" ?> 
<l i braryDescri p t i on 

x ml ns =" s c he ma s . mi c r os of t . c o m/ wi ndows/ 2009/ 1 i b r a r y " > 
<i s L i braryPi nned>true</i sLi braryPi n n e d > 
<i conReference>i mageres. d I I , - 1 0 0 2 < / i conReference> 
<searchConnectorDescri pt i onLi st> 
<searchConnectorDescri pt i on> 

<i s De f a u I t SaveLocat i on>true</i sDefaul tSaveLocati on> 
<si mpl eLocati on> 

< u r I >k n o wn f o I der: { F DD39AD0- . . . }</ ur I > 
<serialized> ...binary data... </ ser i al i zed> 
</ s i mpl eLocati on> 
</ s ea r c hConnect or Desc r i pti on> 
<searchConnectorDescri pti on> 

<i sDefaul t NonOwnerSaveLocat i o n >t r u e 
</i sDefaul t NonOwner SaveLocat i on> 
<si mpl eLocati on> 

<url >k n o wn f o I der: {ED4 824AF- . . . }</ ur I > 
<serialized> ...binary data... </ ser i al i zed> 
</si mpl eLocati on> 
</ s ea r c hConnect or Desc r i pti on> 
</ s ea r c hConnect or Desc r i pti onLi st> 
</ I i braryDescri pti on> 

The folders of this library are all standard ones, so they are listed using known 
folders GUI Ds (the two elements in bold). I doubt you want to process such a 
file manually, so using the API discussed earlier seems the best approach. 



DirectX for Forms 

The DirectX libraries have been part of the Windows API for a longtime, but 
have always been regarded as a separate user i nterface model , mostly good for 
games or high-performance 3D graphics. I n Wi ndows 7 for thefi rst ti me, some 
of the features of DirectX can be used by standard applications, ashappensin 
the.NET Framework when using the Windows Presentation Foundation, WPF. 

Windows Vista introduced a new infrastructure for DirectX called Windows 
Display Driver Model (WDDM), which lets multiple applications share the ser- 
vices of theGraphical Processing Unit (so that DirectX can also be used by non 
full-screen applications). This feature was actually used in Vista by the Desktop 
Windows Manager to display Flip3D and theAero Glass effect. A further big 
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change comes with Windows 7, which makes avail able a new set of DirectX 
APIs that you can use to let standard applications display 2D and 3D graphic, 
text, and i mages i n a much faster way. M icrosoft has promised to make Dir- 
ect2D available also as a Vista update 50 . 

One of the changes, for example, isthe ability to use one of theDirect2D librar- 
ies for pai nti ng a standard form or visual component. You can even mix 
standard GDI output (based on theTCanvas class in the VCL) and the new Dir- 
ect2D output (for which you can usethenewTDi rect 2DCanvas class), as we'll 
see i n practi ce i n the next secti on . 



Direct 2D 

The native VCL support for Direct2D isbased on an abstraction of the existing 
TCa n v a s class. The Graphics unit defines a new base class, called 
T C u s t omCanvas , from which TCa n v a s now inherits along with the new 
T D i rect 2DCanvas class (which in turn is defined in the new Direct2D unit). 
For compati bi I ity purposes, most of the existi ng methods of T C a n v a s also sti 1 1 
work with the new Direct2D class. 

There are a few extra methods, but you access most of the specific Di rect2D 
features by usingtheRenderTarget interface (of type I D2DlRenderTarget ). 
This acts likea Hand I e for theTCanvas , butitisaCOM interface providing 
ready to use methods rather than bei ng a handle you can pass to specific API 
functions. Other low-level features are accessi bl e using theD2 DF act or y and 
DWr i teFactory methods of theTDi rect 2DCanvas class. 

Thisiswhyif you look at the methods of theTDi rect 2DCanvas class, itwill 
seem thereis very little on top of traditional GDI programming. However, if 
you look at the methods of the I D 2 D 1 R e n d e r T a r g e t i nterface, you'l I see the 
huge changes. For example, drawing methods i nd ude D r awBi t ma p , Dr a wLi ne, 
DrawRectangl e,Dr awRoundedRect angl e,DrawEI I i pse,DrawGeometry, 
DrawText,DrawTextLayout, and D r a wG I y p h R u n . M ost of these drawi ng 
methods output only the border of the correspondi ng shape or element, whi le a 
si mi I ar set of fi 1 1 i ng methods use the brush to color the surface of the element. 



50 Di rect2D support for Vista is avai lable as part of a platform update at http:// supportmi- 
crosoft.com/ kb/ 971644. N oti ce al so that there i s no expectati on to have thi s feature also 
avai lable on Windows XP, as the underlying driver technology was much different. 
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The interface also supports transformations, layers, anti-aliasing, DPI settings, 
and status snapshots. 

A lot of the power of Di rect2D comes from the much more powerful graphic 
resources, including pens, brushes and fonts. As we'll see there is full support 
for gradients and other complex schemes. TheDirect2D unit defines several 
new graphic objects, which don't inherit from their GDI counterparts or have 
common ancestors (as it happens for the Canvas) . The Di rect2D resources are 
managed by specific classes inheriting fromTDi r ect 2 DG r aphi csObj ect 51 , 
which often have constructors taki ng the correspondi ng GDI resource as para- 
meter. Direct2D resource classes includeTDi r ec 1 2 DBr us h , TDi rect 2DPen, 
andTDi r ect 2 D F o n t . 

Most other features, from colors to points, use new specific classes rather than 
the traditional ones, typically because their definition changes considerably. 
Points and all coordinates in Direct2D are based on floating point numbers, 
rather the i ntegral ones. This is a huge difference. Agai n, there are hel per func- 
tions for creati ng these new objects and conversions function for converti ng 
fromtheirGDI counterparts. We'll see a few examples in the foil owing demos. 

Direct2D for a Form or a Canvas 

1 1 i s now ti me to start I ooki ng at a f i rst si mpl e exampl e of D i rect2 D , cal I ed 

D2Dlntro. All you have to do to start experimenting with this technology is to 

create a Direct2D painting surface in theOn P a i nt event handler of a form: 

procedure TD2DForm. FormPai nt( Sender: TObject); 
va r 

d 2 d Canvas: TDi rect2DCanvas; 
I : Integer; 
begi n 

d2dCanvas := TDi r ec t 2 DCa n v a s . Cr e a t e ( Ca n v a s , ClientRect); 
d2dCanvas. Brush. Assi gn( Canvas. Brush) ; 
d 2 d Canvas. Begi nDraw; 
try 

d 2 d Ca n v a s . B r u s h . Co I o r := c I Red; 
d 2 d Canvas. Pen. Color : = clBlue; 
f or I : = 1 t o 10 do 
begi n 



51 Oneof the advantages of using these Direct2D resources is that they are owned bytheir 
painting canvas and are disposed automatically when this is released. This makes it easi- 
er to manage these resources and much more difficult to incur in resource memory leaks 
(which are quite dangerous in the GDI world). On the other hand remember that when 
you create a graphic resource for a Direct2DCanvas you cannot use it in another one. 
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d2dCanvas. Brush. Handl e. Set Op a c i ty( 0. 1 * I); 
d2dCanvas. El I i pse( 1 0 +1* 2 0,1 0 +1* 2 0, 
500-1*20,500-1*20); 

end; 
finally 

d 2 d Canvas. End Draw; 
d 2d Canvas, Free; 
end; 
end; 

TheTDi rect 2DCanvas object is created passing the GDI canvas as parameter, 
which is only one of the available options as I 'II cover next. You can keep that 
object around or createanew one each time. What it important, though, isthat 
all output operations take place between the Beg i n Dr a w and End Dr a w calls 52 . 

The program draws a series of concentric circles, using the El I i pse method, 
changing each time the opacity (or transparency) of the brush, which hasa 
value between 0 and 1 This is one of the many features of the I D2 Dl Br us h 
object (accessible with the Handl e of theTDi r ec 1 2 DBr us h object). Here can 
see the visual effect, although the black and white version in the printed book 
makes the effect I ess clear than the full color version of the PDF. 




52 This coding style allows all drawing commands to be completed "off-screen" and then 
displayed, to avoid "flicker" and other unwanted effects. For slow operations, though, 
you'll see only the final result... after some delay. 
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This fi rst demo program has a second feature. By selecti ng the local menu you 

can switch from painting on the GDI canvas to painting directly on the form. 

The menu items set the local f UseCanvas field, used to determine which of the 

constructors to call: 

procedure TD2DForm. FormPai nt( Sender: TObject); 
va r 

d 2 d Canvas: TDi rect2DCanvas; 
begi n 

i f f UseCanvas t hen 

d2dCanvas := TDi r ec t 2 DCa n v a s . Cr e a t e ( 
Canvas, ClientRect) 

else 

d2dCanvas := TDi r ec t 2 DCa n v a s . Cr e a t e ( Ha nd I e ) ; 
d 2 d Canvas. Begi nDraw; 
... // as in pr evi ous listing 

Depending on which of theTDi rect 2DCanvas you call, the VCL will initialize 
the underlyi ngl D2DlHwndRenderTarget i nterface i n different ways. I f you 
passtheCanvas (ortheHandl e totheCanvas device context) and an rectan- 
gular area, Delphi will call theCr ea t eDCRenderTarget function that let's you 
merge Direct2D and GDI calls over the same output surface. If you pass the 
form Ha n die, instead, the VCL ends up callingCr e at eHwnd Render Ta r get , 
which creates a specialized and optimized Direct2D output surface. 

The notable difference, in the demo program, is that the native Direct2D sur- 
face will have a dark background, and the opaque brush will be merged with 
that, rather than the form color. You can change this by cleaning up the back- 
ground by calling the CI ear method of the underlying interface: 

d2dCanvas. RenderTarget. CI ear ( D2DlCol orF (cl Whi t e) ) ; 

Notice i n this statement the conversion of a standard VCL color to its counter- 
part as a D2D1 Co I or F type. 

Mixed Canvases 

As I just mentioned, by creating a Direct2D surface tied to a Canvas (and its 
device context) you can merge output cal Is from both techniques whi le produ- 
cing the output. This is also interesti ng as a way to figure out the differences i n 
those output operations. 

As an example consider the following pai nti ng code, which produces two circles 
on the left and right of the forms with two lines crossing over them (actually the 
GDI circle hides the Direct2D lines, but that's not the point of the demo as it 
depends on the specific brush being used): 



Marco Cantu, Delphi 2010 Handbook 



148 - Chapter 5: The VCL and Windows 7 



uses 

Di r e c 1 2 D, D2D1; 

procedure Tf or mMi x. For mPai nt (Sender: TObject); 
var 

d 2 d Canvas: TDi rect2DCanvas; 
begi n 

d2dCanvas := Tdi rect2DCanvas. Create (Canvas, 

Rect (0, 0, Wi dt h, Hei ght ) ) ; 
d 2d Canvas. Begi nDraw; 
try 

d2dCanvas. Brush. Color := cl White; 
d 2 d Canvas. Pen. Color : = clBlack; 

d2dCanvas. RenderTar get . CI ear ( D2 D 1 Co I o r F (clWhite)); 

d2dCanvas. El I i pse ( 1 0 0, 1 0 0, Width div 2, Height - 100); 

d2dCanvas. DrawLi ne (D2DlPointF (100, 100), 
D 2 D 1 P o i nt F ( Wi dt h - 100, Hei ght - 100) ) ; 
finally 

d 2d Canvas. End Draw; 

d2dCanvas. Free; 
end; 

Canvas. El I i pse (Width div 2, 100, Width - 100, Height - 100); 
Canvas. MoveTo (110, 110) ; 
Canvas. Li neTo ( Wi dt h - 90, Hei ght - 90) ; 
end; 

Whileyou draw a circle in the same exact way, drawing lines with the two 
approaches is different as the Direct2D surfacehasaDr awLi ne method taking 
D2DlPointF parameters (which in turn use floating point coordinates). The 
canvas, instead, uses the classic MoveTo and Li neTo calls. 

The most significant difference, however, is in the output. By using anti-ali- 
asing techniques, theDirect2D output is much smoother. Here is the central 
portion of the output image captured and zoomed to highlight the effect: 




If it wasn't for the fact that this feature is currently avail able only in Windows 7 
(with promises to port it back to Vista) I'd certainly switch to it if only for the 
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nicer and cleaner output effect. Another good reason, though is the extra fea- 
tures you gain, I ike the gradient brushes demonstrated next 53 . 



Gradients to the Max (With no Canvas) 

There are many more features of Di rect2D than I have ti me to demonstrate i n 
this chapter. So I'll try to show a few more intriguing capabilities in the coming 
example, called D2DGradients. This program uses a different approach, as it 
creates and keeps around the Di rect2DCanvas object, rather than creati ng a 
new one for each paint operation. I n practice, the form has a private field 
declared as: 

pr i vat e 

d2dCanvas: T D i r ec 1 2 DCa n v a s ; 

This field gets initialized as the window itself iscreated, modified when the 
form is re- si zed, and used by the pai nti ng code. H ere is the creati ng and resiz- 
ingcode: 

procedure TFormGradi ents. Create Wn d ; 
begi n 

inherited; 

d2dCanvas := T D i r ec 1 2 DCa n v a s . Cr e a t e ( Ha nd I e ) ; 
end; 

procedure TFormGradi ents. FormResi ze(Sender: TObject); 
begi n 

if Assi gned ( d2dCanvas) t hen 

( d 2 dCa n va s . Re nd e r Ta r g e t as I D2DlHwndRenderTar get ) . 
Resi ze( D 2 D 1 S i zeU( CI i entWi dth, ClientHeight)); 

end; 

The resize method is specific to the i nterface used if the render target is created 
from a windows handle. Notice that the program also checks for Direct2D sup- 
port before starti ng, provi ng a specific error message: 

procedure TFormGradi ents. FormCreate(Sender: TObject); 
begi n 

if not T D i rect2DCanvas. Supported then 

raise Except i on. Cr eat e( ' Di rect 2D not supported!'); 

end; 



53 For a rather complete comparison of GDI and Direct2D, including optimization of each 
technique, you can seethe DirectX developer blog post at: 

http://blogs.msdn.com/directx/ archive/ 2009/ 09/ 29/ comparing-direct2d-and-gdi.aspx 
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Now that I 've descri bed the basic structure, let me focus on the actual pai nti ng 

code. The f i rst thi ng the program does i s pai nt the enti re surface of the form 

with a gradient brush: 

procedure T F o r mG radi ents. FormPai nt( Sender: TObject); 
va r 

gradColors: array of TColor; 
Center: TD2DlPoi nt2F; 
begi n 

d 2 d Canvas. Begi nDraw; 
try 

// define the gradient colors 
Set Lengt h (gradColors, 4); 
gradColors [0] : = clBlue; 
gradColors [1] : = c I Aqua; 
gradColors [2] := c I Navy; 
gradColors [3] : = clFuchsia; 

// create the gradient brush, using colors and points 
Center : = D2DlPoi ntF ( 1 0 0, 1 0 0 ) ; 
d2d Canvas. Brush. Handle := 

d 2 d C a nvas . Cr ea t e B r us h (gradColors, Center, 

D 2 D 1 P o i ntF ( 3 0 0, 2 0 0 ) , 9 0 0, 9 0 0 ) ; 

// paint the entire form with the gradient brush 

d2dCanvas. Rectangl e( 0, 0, CllentWIdth + 50, CllentHelght + 50); 

This prints the background with gradients ranging from various tones of blue to 

magenta 54 . Next step isto write text painted with a slightly different gradient 

brush, based on the same colors. This new brush isassigned to the font, while 

the canvas brush iscleared to avoid seeing a rectangle around the text: 

// define a font with a gradient brush 
d 2dCa nvas . Font. Size : = 60; 
d2dCanvas. Font. Brush. Handl e := 

d 2 d C a nvas . Cr ea t e B r us h (gradColors, Center, 
D2 Dl P o i ntF ( 3 0 0, 3 0 0 ) , 6 0 0, 6 0 0 ) ; ; 
d2dCanvas. Font. Styl e : = [f sBol d] ; 
d2dCanvas. Brush. Styl e := bsClear; 

// output some text with the current font 

strText : = ' Del phi 2010'; 

d2dCanvas. TextOut ( 200, 100, strText); 

A gradient text over a gradient background starts looking interesting (and quite 
hard to accomplish in GDI terms), but there is more. 



54 I won't try to show the output of this code here, asagray-scaleprintwon'tbeadequate. 
I f you are i nterested you can have a I ook at my bl og post: 
http:/ / bl og. marcocantu .com/ bl og/ d i rect2d_ del ph i 20 10 . html 
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The program uses a transformation matrix for rotating the text while dimming 
its colors (by changi ng the opacity) : 
va r 

mat ri x: T D2 DMa t ri x 3 x 2 F ; 
begi n 

fori : = 1 t o 10 do 
begi n 

D2DlMakeRot at eMat r i x (I * 6, D2DlPoi nt F( 50, 5 0 ), ©matrix); 
d2dCanvas. RenderTarget. SetTransform( matri x); 
d2dCanvas. Font. Brush. Handl e. SetOpaci ty( 1 - I * 0.1); 
d2dCanvas. TextOut ( 200, 100, strText); 
end; 

There is a little morecodeto get the original transformation matrix and reas- 
sign it at the end, but the three code snippets just displayed sum up the code of 
theOnPai nt event handler of this example. 

For another example of Direct2D in Delphi, you can refer to the foil owing post 
by Pawel Glowacki , who translated one of the M icrosoft SDK demos (the 
Advanced Path Geometries Demo) in Delphi: 

| htt p: // bl ogs. emba reader o. com/ pawel gl owacki / 2 0 0 9 / 1 2 / 0 8 / 3 8 8 6 1 

DirectWrite 

We have seen that we can use the basic text drawi ng functions of Di rect2D 
most I ike the GDI ones, but support for the precise display of text has much 
i mproved compared to the past. The new i nterfaces for managi ng font fami I ies, 
text layouts, text formats, and the I ike are collectively known as DirectWrite. 

In Delphi you can access to the various DirectWrite objects using the factory 
object returned by theDWr i teFactory global function of theDirect2D unit 
(which creates and initializes a singleton behind the scenes, implementing the 
I DWr i teFactory interface). You can use this interface, defined in the usual 
D2D1 unit, to create most of the core formatti ng objects. The I ist is extremely 
long and itwould be somewhat pointless to show it here. 

Instead, I'd rather focus on a simple example, which usesaTDi rect 2DCanvas 
and a few Di rectWrite objects to draw a couple of stri ngs on the form. The spe- 
cific local variables used by theF or mP a i nt method of the main form of the 
DWrite example are: 

idwtFormat: I DWr i t eText For mat ; 
idwtLayoJt: I DWr i t eText Layout ; 
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matrix: DWRI TE_ MAT R I X; 

The first operation is the creation of a text format, obtained by passing the 
interface to be initialized totheCr ea t e T e x t For ma t method. The parameters 
are the font name, the (missing) font family, a series of constant display para- 
meters, the size 35, a locale, and the object to be initialized: 

DWri teFactory. CreateTextFormatf ' Ar I a I ' , n i I , 

DWRITE FONT WEIGHT LIGHT, DWRI TE FONT STYLE NORMAL, 
DWRI TE~ FONT ~ STRETCH, SEMI _ CONDENSED, 
35, ' en- US' , i d wt F o r ma t ) ; 

The program passes this text format to the Dr awText method of the 
Render Ta r get low-level object, along with the text to display, its length, the 
output rectangle, and a brush: 

s t r Text : = ' Hel I o, Dei phi ' ; 

d2dCanvas. RenderTarget. DrawText (PChar(strText), 
Length (strText), idwtFormat, 

Rect (10, 10, 500, 200), d2d Canvas. Brush. Handl e) ; 

I n the code above I pass a T Rect totheDr awText function where it would 
expect a D 2 D 1 _ R E C T _ F structure. This is possible because the latter data struc- 
ture has an I mpl i ci t conversion operator 55 defined as: 

class operator I mpl i c i t ( AVa I u e : TRect): D2D_RECT_F; 

There are similar conversion operators for other rectangle data structures and a 
couple of poi nt data structures of the D2D1 unit. 

The second output operation done by the program i n the F o r mP a i n t event 
handler uses the same technique, but with a bold, oblique, and expanded text 
format. Two new cal I s al i gn the text to the center and set very ti ght I i ne spaci ng 
(the value 28): 

strText := 'This is a DirectWrite oblique example'; 

DWri teFactory. CreateTextFormatf ' Ar i al ', ni I , 

DWRITE FONT WEIGHT EXTRA BOLD, DWRITE FONT STYLE OBLIQUE, 
DWRI TE~ FONT~STRETCH_EXTRA_ EXPANDED, 35, 'en-US', "id wt For mat); 

i d wt For mat . Set Text Al i gnment ( DWRI TE_TEXT_ALI GNMENT_ CENTER) ; 
i dwtFormat. SetLi neSpaci ng ( 

DWRITE LI NE SPACI NG_METHOD_UNI FORM, 28, 0); 

d2dCanvas. RenderTarget. DrawText (PChar(strText), 
Length (strText), idwtFormat, 

Rect ( 1 0, 1 1 0, 5 0 0, 2 0 0 ), d 2 dCa n va s . Br us h . Ha nd I e ) ; 



55 For more detail son operators overloading in general and conversion operators in partic- 
ular you can refer to my Delphi 2007 Handbook. 
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The stati c output of the form shoul d I ook I i ke the fol I owi ng i mage: 

Hello, Delphi 

This is a DirectWrite 
oblique example 



Using the Windows I maging 
Component 

Another new graphic- related feature of the VCL is its support for the Windows 
I magi ng Component (Wl C) . This is a M icrosoft framework for working with 
images and their metadata, which supports several image formats and can be 
extended with new i mage formats by software and hardware vendors ( I i ke 
digital camera makers). Not only can theWICcan display images, but it has 
also a lot of i mage processi ng capabi I ities bui It i nto it and i ndependent from 
the actual image format. 

The WIC is available in Windows 7 and in Vista, but it is also possibleto install 
it on WindowsXP 56 , making it availableon a broader base than some of the 
technologies discussed earlier in this chapter. By default, WIC has the fol lowing 
built-in image formats (here listed with the corresponding mi me types): 

• BMP (Windows Bitmap Format), BMP Specification v5 

• Gl F (Graphics I nterchange Format 89a), Gl F Specification 89a/ 89m 

• ICO (Icon Format) 

• J PEG (J oint Photographic Experts Group), J FIF Specification 102 

• PNG (Portable Network Graphics), PNG Specification 12 

• TIFF (Tagged I mage File Format), TIFF Specification 6.0 
. Windows Media Photo, HD Photo Specification 10 



56 For the i nstal I ati on of the Wi ndows I magi ng Component i n Wi ndows X P you can see cor- 
responding page of the Microsoft download site at http://www.microsoft.com/ 
downloads/ details.aspx?Familyl D=8e0I1506-6307-445b-b950-2Bdef45ddd8 or type in 
you r browser the shortened versi on http:/ / bi 1. 1 y/ aQn45N 
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Delphi 2010 support for the Windows I maging Component is based on the new 
TWI CI mage class, aTGr a p h i c descendant defined in theGraphics unit like the 
classic T Me t a f i I e andTBi tmap VCL classes. The image formats handled by 
thiscomponent are all those mentioned earlier, as you can seein the enumera- 
tion underlying the I mageFormat property: 

TWI CI mage For mat = (wifBmp, wifPng, wifjpeg, 
wifGif, wifTiff, wifWMPhoto, wifOther); 

However, theT I ma g e component registers only theTI FF graphic format (or to 

be more precise, file extensions) for use with the TWI CI mage class, as you can 

see from the fol I owi ng VCL code sni ppet: 

constructor TFI I eFormatsLI st. Create; 
begl n 

inherited Create; 

Ad d ( ' wmf , SVMet af I I es, 0, T Me t a f Me); 
Addf'emr, S VE n h Met af I I es , 0, TMetafile); 
Ad d ( ' i co' , SVI cons, 0, Tl con) ; 
Add ( 'tiff, SVTI FFI mages, 0, TWI CI mage) ; 
Add ( ' tif , SVTI FFI mages, 0, TWI CI mage) ; 
Ad d ( ' bmp' , S V B i t maps, 0, TBi t map) ; 
end; 

I ncluding specific units, likethej PEG unit, the VCL registers more formats: 

■ initialization 

TPi cture. Regi sterFi I eFormatf ' j peg' , sj PEGI mageFi I e, TJ PEGI mage); 
Tpi cture. Regi sterFi I eFormatf ' j pg' , sj PEGI mageFi I e, TJ PEGI mage) ; 

This means that in Delphi 2010, when running on aversion of Windows with 
WIC support, you can manage thej PG files using this last component. All you 
have to do is to declare the fol I owing: 

| TPi cture. Regi sterFi I eFor ma t ('jpg', 'JPEG Image', TWI CI mage); 

This iscode you'll find in theTiffViewer example, which let's you open in an 
I mage component a TIFF oraj PEG file in an I mage component using the 
TWI CI mage class.You don't have to do anything special to gain this support, as 
all you have to do is to open the file (I ma gel. Pi cture. LoadFromFi I e) and 
the I mage component wi 1 1 use the support cl ass registered for the f i I e format. 



Wl C Transformations 

Again, there is very little you have to do to useTIFF support... just open afilein 
the I mage component. However, it is important to notice that there are two 
sides to the WIC. One is loading and saving files with given formats. The 
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second side is the ability to process the i mages. To accomplish thisyou have to 
access to the I Wl CI magi ngFactory interface, avail able through the 
I ma g i ngFactory property of theT Wl CI ma g e class. This COM factory lets you 
create specific COM objects that expose given i nterfaces: 

• the I Wl CFormatConverter i nterface to converter formats 

• the I Wl C B i t ma p S c a I e r i nterfaces for the seal i ng bitmap 

. the I Wl C B i t ma p C I i p p e r i nterfaces for bitmap cl i ppi ng support 

• thel Wl CBi tmapFI i pRotator interfaces to flip and rotate images 

• the I Wl CCol orTransform and 1 Wl CCol orContext i nterfaces that can be 
used for color management 

Again, there is a plethora of methods and options, much more than I can cover 
in thissection. What I 'II do, instead, isto show you a practical exampleof how a 
Delphi application can manipulate images. The first part of the code extracts 
i nformati on from the image currently loaded in theT Wl CI mage object, using 
the I Wl C B i t ma p i nterface: 
va r 

wl c I mg : TWI CI ma ge ; 
i B mp Source: I Wl CBi tmapSource; 
p u i Wl dt h, p u i Hel ght : Ul NT; 
begi n 

if I ma gel. Picture. Graphic is T Wl CI ma g e then 
begi n 

wiclmg := TWI CI mage ( I ma ge 1 . P I c t u r e . Gr a p h I c ) ; 
i Bmp Source : = wiclmg. Handle as I Wl CBi tmapSource; 
i Bmp Source. GetPixel For ma t ( p P i x e I For ma t); 
i Bmp Source. GetSi ze( pui Wi dth, pui Hei ght) ; 
Log ('Original: ' + IntToStr (pui Wi dth) 
+ 7 ' + IntToStr ( pui Hei ght ) ) ; 

This outputs the width and and height of the bitmap. The second step isto 
extract the flip/ rotator interface, assign it to the source bitmap, askforagiven 
operation (in this case a 90 degree rotation), and again display the width and 
height of the rotated i mage: 
va r 

i Fl i pRot : I Wl CBi t mapFI i pRotator; 
i Bmp Source: I Wl CBi tmapSource; 
pui Wi d t h 2 , pui Hei ght2: Ul NT; 
begi n 

wl cl mg. I magi ngFactory. CreateBI tmapFI i pRotator) I Fl I pRot) ; 
IFIIpRot. Initialize (IB mp Source, WICBItmapTransformRotate90); 
i Fl i pRot. GetSi ze( pui Wi dth2, pui Hel ght 2) ; 
Log ('Rotated: ' + IntToStr ( pui Wi d t h 2 ) + '/' + 
IntToStr ( pui Hei ght 2) ) ; 
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Finally we have to extract the rotated bitmap (passing the correct dimensions 
for the rectangle of the source i mage) and assign it as the source of the 
TWI CI mage object: 
var 

wi c Bi t ma p : I Wl C B i t ma p ; 
begi n 

wi cl mg. I magi ngFactory. CreateBi t ma p F r o mSo u r c e Re c t ( 
iFlipRot, 0, 0, p u i Wi d t h 2 , pui Hei ght2, wicBitmap); 

if As s i gned ( wi c Bi t ma p) then 
wi cl mg. Handl e : = wi c B i t ma p ; 

I ma gel. Repai nt; 

You can see a sample result i n the i mage below. Consider that you can do si m- 

ilar transformation for each file format, but need to load them in the 

TWI Cl mage object first. In this case I've loaded and rotated a sample TIF image 

(the test page of a FAX), which is included along with the source code of the 

example: 




Other New VCL Features 

Not all new VCL features areadvances at the operati ng system and SDK level 
related with Windows 7. The library has seen countless small improvements. 
I 'm going to focus on them in the remaining portion of this chapter. Let me 
start with some noteworthy but simpler changes (this is not an exhaustive list, 
as I picked what I felt most relevant), while I 'II later focus on improved prop- 
erty editors and changesin multi-language support. Here is a list of these 
notable changes: 

• All grids (DrawGrid, StringGrid, DBGrid, and also the grid-descendant 
ValueEditor control) now support themes. See Chapter 7for an actual 
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example featuring a DBGrid. Grids and the ValueEditor also support gradi- 
ents and other graphical enhancements. 

• The ProgressBar components now supports 32-bit val ues for the properties 
P o s i t i o n , Mi n , and Ma x . Older Windows platforms won't support them, 
though. 

• The A s sign method of a T B i t ma p i mage can take also a T I con parameter, 
letting you convert an icon into bitmap. 

• The two buttons (of class T Ed i t Bu 1 1 o n ) on thesidesof theButtonedEdit 
component (introduced in Delphi 2009) now support individual hints. 

• When usi ng the CategoryButtons control (the one used i n the Del phi IDE for 
the Tools Palette) you can enable in-place editing for the categories. The 
component has seen also several other improvement and fixes. 

• The CheckListBox component has a new CheckAl I method. 

• The SpeedButton control can now be properly pai nted over a Glass surface. 

• The global Screen object has a new C a p t i o n F o n t property, that works 
together the Me s s a g e F o n t property, i ntroduced i n Del phi 2009 and used to 
determi ne the font of some of the message di al ogs. 



Property Editors for Actions and Dates 

Beside the changes in VCL components, Delphi 2010 has a couple of very inter- 
est ng additions i n terms of changes to property editors, which spawn across 
multi pie components. Every ti me you have a T D a t e property, you can now use 
a M onthCal endar to pi ck a val ue at desi gn ti me: 



Object Inspector 



| Properties | Events 
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A much more useful update was made to the editor of the Action property. In 
the past you could only pick one of the avail able actions from a drop down list, 
now you can also define a new (custom) action or a new standard action in one 
of the avai I abl e categori es: 



Object Inspector 



Butt-on 1 TButton 
| Properties | Events I 



13 



Action 
Align 
AlignWithMarg 
Anchors 
BiDiMode 
Cancel 
Caption 



EditCutl 



New Standard Action 



EditCopyl 
EditCutl 



, EditPastel 
Command Li nkJ%TC~| 
Constraints 
Cursor 
CustomHint 
Default 



fTSize Constraints) 
crDefault 

□ False 



(No Category) 

Edit 

Format 

Help 

Wi n d ow 



DataSnap Client 



File > 




TFileGpen 


Search ► 




TFileOpenWith 


Tab ► 




TFileSaveAs 


List ► 




TFilePrintSetup 


Dialog ► 




TFilePageSetup 


Internet ► 




TFileRun 


Took ► 




TFileExit 


Dataset ► 




TBrowseFo rFo 1 d er 



This feature 57 is avai I able only if the current form (or current designer) hosts or 
is connected with an ActionList or ActionManager component. 



Input Language and Language Libraries 

In Delphi 2010 there have been a couple of significant changes for developers 

who build international applications. The first is that the Windows 

wm_ I nput LangChange message now triggers an i nternal component message, 

cmj nput LangChange, which is broadcasted to all windowed controls. You can 

intercept and process this message in a TWi nControl descendant, by adding a 

message handler method like: 

procedure C Ml nput LangChange) var Message: TMessage); 
message CMJ NP UT LANGCHANGE ; 



57 The new Action property editor was first mentioned on his blog by Chris Bensen at: 
http://chrisbensen.blogspot.com/2009/08/rad-studio-2010-actions.html 
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The second change relates to the way the VCL loads localized resource files in 
the LoadResourceModul e function of the System unit. This is used, in particu- 
lar, with resource files generated by the Internal Translation Manager 
(activated with the Project | Languages menu). I n the past Delphi would use 
either a local override in the system registry or use the current locale specified 
in theRegional Setti ngs of the Control Panel. In Delphi 2010, instead, the VCL 
still looks for the local override in the system registry, but, in case this is not 
set, it uses the default user Ul language (unless the program is running on an 
old version of Windows, in which case the classic behavior is respected). 

The default user Ul language is the active language 58 of the operating system, 
determined intheVCL by calling theGet User Def aul t Ul Language API. In 
other words, by changing the Regional Setti ngs of the Control Panel you will no 
longer affect the resources being loaded for your application. 

Wecould discuss which strategy is more flexible as both have merit, but my 
point here isthatthis is an important change that it not mentioned in the 
Delphi documentation and could easily get overlooked by developers. The 
LoadResourceModul e function of the VCL, responsible for this behavior, has 
been completely rewritten in Delphi 2010, with a different effect depending on 
which version of Windows under which you are running your application. I 
won't delve into the Translation Editor and its behavior here, nor delve into the 
detailed effects of this change, but only warn you about the existence of this 
change 59 . 



Minor Incompatibilities with "Growing" 
Enumerations 

The last thing I want to mention about the VCL is a very subtle change that 
might prevent some existing programs from compiling. Some of the enumera- 
tions used by the VCL, which have not been modified in a longtime, have been 
extended with new values. 



58 All recent version of Windowscan beinstalled with a multilingual support that lets you 
switch the operating system language at run time, rather than reinstalling a new lan- 
guage-specific version of the operating system. 

59 Thanks to J aakkoSalmeniusof Sisulizer for bringingthisto attention in a Delphi forum. 
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One of them isTSh i f t St a t e , which now supports touch and pen operations 

and is defined as: 

TShi ftState = set of (ssShift, ssAlt, ssCtrl, ssLeft, 
ssRight, ssMiddle, ssDouble, ssTouch, ssPen); 

Another enumeration that has a new extra value isT Co n t r o I State. The prob- 
lem arises as you convert one of the enumerated val ues to its numeri c 
counterpart using a direct cast (rather than the Ord function). In Delphi 2009 a 
TCont r ol State valueisstored in a Word, in Delphi 2010 in aCardinal. So, 
following this example, the classic Delphi code below doesn't compile in Delphi 
2010: 

va r 

w : Wo r d ; 
begi n 

w : = Word ( Co n t r o I S t a t e ) 
You can easi ly update it to: 
var 

c : Cardinal; 
begi n 

c : = Cardinal (ControlState); 

These changes have an extremely limited effect, as in general it would be 
recommended to use the Or d function and store the value in an Integer. How- 
ever there are many custom controls that use such a low-level codi ng style, and 
those might get affected and fail with a compiler error. As I 've bumped into two 
such situations, there are certainly few around, so I felt worth mentioning the 
issue... si nee when you realize the problem the fix becomes almost trivial. 



What's Next 

In this chapter I've delved into new features of Windows 7, changes to the VCL 
to address those new capabilities, and other general change to the Del phi com- 
ponent library. One of the most relevant new features of the VCL, partially 
related with Windows 7, is the support for touch and gestures, which is covered 
in the next chapter. After that I 'II move to changes and new features to the 
database part of the VCL. 
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Delphi 



Developer Days 



www.DelphiDeveloperDays.com 
Featuring Marco Cantu and Cary Jensen 



Marco Cantu and Cary Jensen jointly offer Delphi Developer Days, multi-day live 
events with both joint sessions, presented by Marco and Cary together, as well as 
simultaneous tracks, where Cary and Marco break out into separate rooms to 
present individual topics. 

All attendees receive very detailed course books, which cover all topics presented 
by Marco and Cary plus all of the source code. Attendance is limited to keep the 
event intimate so that you'll have the opportunity to ask them about any of the topics 
that they covered, as well explore other Delphi questions that you might have. 
Whether you are using the latest version of Delphi, or are developing with an older 
version, you will come away with loads of information that will improve your develop- 
ment and make you more productive. 

Delphi Developer Days Tour Schedule for 2010 

• Washington DC/BWI Airport Area: May 11-12, 2010 

• Chicago Area: May 14-15, 2010 

• Los Angeles Area: May 17-18, 2010 

• London, UK: May 26-27, 2010 

• Frankfurt, Germany: May 31 - June 1 , 201 0 
Future Dates for Delphi Developer Days 

Marco and Cary plan to add new tour dates in the future. To be notified of addi- 
tional dates, visit http://www.DelphiDeveloperDays.com/NotifyMe.html. 

www.DelphiDeveloperDays.com brought to you by: 



Jensen 




Data 

~ Systems 
~ ~ Inc 



JensenDataSystems.com 
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Chapter 6: Touch 
And Gestures 



With mouses and keyboards being part of the computers landscape si nee the 
Nineties, experimental user interfaces have been focused mostly on script 
recognition (starting with the Apple Newton, theGraffiti input system of Palm 
hand computers, and including tablet PC support in Windows) and voice recog- 
nition. These experi ments have never reached a critical mass or affected 
everyday computer users. 

Over the last couple of years, however, a slow revol ution has started outside of 
the PC realm. The two most prominent and known examples aretheWii con- 
trollers (which receive input from three-dimensional spatial movement) and 
the touch support ofthei Phone (which lets you moveafinger across the screen 
to issue a command) . 

M any people are now expecti ng that this user i nterface revol ution wi 1 1 soon hit 
desktop PCs. Among the companies backing this idea there is Microsoft, which 
added extensive support for touch in Windows 7, and Embarcadero Technolo- 
gies, which is pushing touch and gesture support in Delphi 2010. 

There are many other elements beyond touch, including for example the Sensor 
and Location API that is also part of Windows 7 (which you can use in Delphi 
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by directly interfacing to it). In this chapter, though, I'll cover only touch and 
gestures, focusing specifically on gestures as touch support requires specific 
hardware that is still hardly popular. I'll also cover related VCL features, like 
the new Touch Keyboard control . 



From Single Touch to Multi-Touch 

Touch screens have been around for several years now and have been popular 
in kiosk applications, vertical -market tasks like restaurant ordering systems, 
and to a more limited extent in tablet PCs. The classic touch screen can inter- 
cept the position of your fi nger on the surface, but returns only one given 
coordinate. This makes it quite a rough approximation of the position as your 
finger, unlikea dedicated pen with a more fine tip, will generally touch multiple 
screen pixels at a ti me 60 . 

I n technical terms, a classic touch screen behaves like a mouse sending mouse 
down and mouse up Wi ndows messages to the operati ng system (and hence to 
the application). This is what is now generally called a single-touch system. 

Newer touch screens, i n fact, can i ntercept multi pie pressure poi nts at the same 
time, and send them all in parallel to the system. These multi-touch 61 systems 
bri ng two different advantages. 

First, if you press your bigfinger over the screen, the driver will reduce the 
points in proximity to a single one but with a better resolution, so it would be 
easier to figure out your intended operation. Also, any movement you make 
with your finger on the screen is interpreted in more precise way, making it 
easier to perform gestures. 

Second, you can sel ect two or more on-screen el ements at the same ti me, by 
using two or more fingers. There are currently systems being sold which are 



60 If you've ever tried using the small buttonsof a Windows CE device with your fingers in- 
stead of the specific pen you probably know what I mean. I consider it a dreadful experi- 
ence, but havi ng to use the pen to select a contact and make a phone cal I wi le you are 
walkingiseven less natural that trying to hit the name with your finger, or even your fin- 
gernai I to be more precise! 

61 As odd as it might sound, the term "multi-touch" is actually a trademark of Apple Inc. as 
listed on http://www.apple.com/legal/trademark/appletmlist.html. 
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capable of intercepting up to ten touch positions (and although it would be 
quite odd for a single user to need more, multi-user systems like Microsoft Sur- 
face can benefit from more than ten touch points). You can also move two or 
more fingers on the screen to man ipu I ate the objects you are touching. A classic 
example is stretchi ng a picture by draggi ng away the opposite borders with two 
f i ngers. 

For multi-touch you need support both at the operati ng system level and at the 
hardware level. At the operati ng system level, Windows 7 introduces specific 
system messages, I i ke w m_ t o u c h . Thi s message carri es a wealth of i nformati on 
about the input activities of the user, computes the touch to single coordinates 
plus a couple of key shift states of the traditional mouse messages. 

At the hardware level, you need multi-touch hardware with drivers specifically 
tai lored for Wi ndows 7 (as older touch support drivers wi 1 1 si mply mi mic the 
traditional mouse messages, as in singletouch devices). 

Another way to thi nk about touch versus the mouse (and its derivatives) is to 
consi der that i n the f i rst case the system works with absol ute positi ons, whi I e i n 
the second it is relative movements that matter. When you touch a screen (or 
optionally a touch pad with full touch support), you areindicating a specific 
location. With the mouse (and some movement oriented touch pads) you move 
it from the current position to a new one, but it is the relative movement that 
matters. I n fact, if you I ift the mouse and lower it down i n a different place, the 
effect is like it didn't move! 

Touch Hardware 

You might think that touch hardware comes in the form of touch screens you 
add to your existing PC. This is hardly the case, although some multi-touch 
monitors are starti ng to appear. I n most current offers, touch screens are part 
of a single computing device, either a touch screen laptop computer or an all- 
in-one desktop (or wall-mounted) device. 

H ere I won't provide a complete overview of touch-enabled hardware, but focus 
onlyon Windows 7 enabled devices 62 . Theseincludes portable computers (not- 



62 You can find a very comprehensive hi story and board review of availabletouch hard- 
ware, beyond Windows, in an articleat http://medlibrary.org/medwiki/Multi-touch. 
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ablyfrom Dell and HP), all-in-one devices (mostly from HP), and computers 
with multi-touch touch pads (I ike those from Acer and Dell): 

• A typical touch-enabled laptop (with a rather small screen is) HP'sTouchS- 
mart tx2z and Dell's Latitude XT2, but also machines from Lenovo and Acer. 

• Al I i n one systems from H P i nd ude H P TouchSmart 300 and 600, Del I 's 
Inspiron One 19 Touch, and Sony's Vaio L. 

• I f you are looki ng for an external touch monitor to be attached to an existi ng 
PC, you can refer to the Dell's SX2210T 215"W Multi-Touch Monitor. 

• If you are looking for a simpler solution, consider multi-touch internal touch 
pads, like the one in Dell 's I nspi ron Mini 10. 1 tried it and it looks interest- 
ing. M any recent I aptop computers offer a si mi I ar sol uti on . 



Multi-Touch Pads 

Speaking of multi-touch pads, I 'm convinced they should probably be favored 
above touch screens, not just because of the reduced cost. Adding a large multi- 
touch touch pad to an existi ng computer would be a very good sol uti on for 
movi ng to multi-touch. A touch pad works better than a touch screen for stand- 
ard PC users, as touching the screen is very ineffective both in terms of arm 
fatigue and in terms of covering what you are looking at with your hand. 

I noticed, in particular, thenice looking Bamboo Touch device from Wacom 
(and even bought one), but thisdevice comes up very short in terms of Win- 
dows 7 support, as its driver maps multi-touch interaction to traditional mouse 
operations and the driver uses relative movements rather than absol ute posi- 
ti ons. 1 1 i s not that the devi ce won't be capabl e, but the dri ver fal I s quite short. 
Actually Microsoft itself is not pushing this class of hardware, favori ng touch 
screens, butl'd argue this is OK for special purpose PCs, but not for main- 
stream office users. 



The Theory Behind Gestures 

As I mentioned in the introduction of the chapter, the main topic is touch sup- 
port but with the specific focus on gestures. 

But what is a gesture? It is basically a movement of the input device foil owing a 
specific path and withi n a given ti me. The path of a gesture is not absol ute i n its 
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extension, but is represented by a vector of points which can generally be scaled 
at wil I . This means you can make a more ample or compact gesture and they'll 
still both be recognized. In other words, a gesture is represented by a sequence 
of poi nts and some further parameters that are passed to an engi ne capable to 
recognizing a gesture against a given gestures catalog. 

What is very relevant to notice up front is that I i ntentional ly used the vague 
term of "input device", as gestures can beissued not only by moving a finger 
over a touch screen but also by movi ng the mouse over a standard flat surface. 

In other words, while multi-touch support requires specific hardware and oper- 
ati ng system support, gestures support can work on any version of Wi ndows 
and with any i nput device (except a keyboard, of course, but i ncl udi ng the 
si ngle touch pads that most I aptops have these days) . 

Towards a Touch-Based Ul 

Supporting touch- based interfaces is not just a matter of using larger buttons 
and virtual touch keyboards, but often requires a significant redesign of the 
program user interface. Every input operation should account for more impre- 
ciseinput, keyboard actions should be minimized (using auto complete 
features I i ke many eel I phones do, for example), and you should move away 
from the traditional user interface whenever required. 

A very good example of an i nnovative approach is the use of gestures, as I 
covered in the first part of the chapter. When you have a touch screen, perform- 
i ng a gesture wi 1 1 general I y be much easi er than sel ecti ng a tool bar button . 
However, for regular PC users, pressing a shortcut key will remain faster than 
both the mouse and the touch operation. 

I n other words, whi le i n the past we had to balance the needs to mouse users 
and keyboard users, now we have a thi rd category (touch or i nteracti ve users) 
to take into account in general purpose applications. Of course, if the program 
is not for the PC but for a dedicated computer, it might not have a mouse or a 
keyboard and this solves part of the problem. But with the introduction of 
touch screen in regular PCs, we'll have to face the problem of different users 
havi ng different i nput preferences when based on the same hardware. 
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The Gesture Manager of the VCL 

In Delphi 2010 the VCL adds to its core features a gesture management archi- 
tecture. This is built into theT Con t rol hierarchy, with the new On Ge st ure 
event surfacing in all visual components. However, the actual gesture manage- 
ment code can be selectively compiled into the VCL or not, thus avoiding the 
extra overhead 63 i n case you are not i nterested i n usi ng gestures support. 

The core cl ass of this architecture is the new GestureM anager component. 1 1 
can be used to handle gestures performed with touch hardware, pen and tablet 
i nput or even traditional mouse i nput. The GestureM anager def i nes a set of 
standard and predefined gestures, but you can add custom gestures directly at 
the application level or by installing packages that register gestures. 

The GestureM anager also handles special "interactive" gestures that require 
touch hardware. These special gestures include panning, zooming, rotating, 
two finger taps, and press and tap operations. 

As you enable gestures for a given control (by hooki ng the GestureM anager 
component to it), any gesture performed over the control 64 will fire the 
On Ge s t ure event of the control, unless there is a specific action tied to it. 

A Basic Gesture Example 

Rather than describing the complete VCL gesturing architecture in theory, let 
us start by bui Idi ng a very si mple fi rst example I 've called GesturesOl. The pro- 
gram has a form with a panel and a memo control, pi us the GestureM anager 
component. This last component doesn't have specific setting, as its editor let's 
you add custom gestures to it, something we will focus on later. 

The management of gestures takes pi ace in the To u c h property of the target 
control, for example the form. This property is slightly a misnomer, as it 
handles all touch and gesture related operations, through its sub- properties. If 



63 The gestures overhead is about 300KB to 400KB in executable size, which is why it was 
worth taking additional measures to avoid it when not needed. 

64 Performi ng a gesture over the control means maki ng the proper mouse or f i nger move- 
ment starting over the control. If you move over other controls while performing the ges- 
tures, it won't matter. What is relevant is the starting position. 
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you expand theT o u c h property (which is 
of typeT T o u c h Ma n a g e r ) for a control , you 
should see somethi ng si mi lar to the i mage 
on the ri ght, with the Gestures sub- prop- 
erty disabled astheGes t ur eManager sub- 
property is not assigned. 

As soon as you connect a GestureM anager 
control , the i nterface of the Object 
I nspector for the property changes consid- 
erably, with the col lections of available 
gestures (by default the St and a r d ones) 
listed under theGe s t u r e s property, as 
you can see i n the second i mage here on 
the right. 

I n the Object I nspector you can also 
expand the Standard gestures node, and 
enableor disable individual gestures for 
the control, as depicted in the third image of the sequence. 

Each element of this collection of gestures (aTGestureCol I ecti onl t em ele- 
ment) has a name, a graphical representation, and (optionally) the action to 
which it istied. We'll get to using 
actions for gestures in a second 
example. For now, we can just enable all 
of the gestures for the form (and the 
panel). This is done more easily in the 
gestures col lections editor rather than 
i n the Object I nspector, as you have but- 
tons to select and deselect all standard 
actions. Thegestures collections editor 
i s vi si bl e here on the ri ght. 

I n this editor you can see the gesture 
name and graphical description, its 
internal identifier (a constant) and a 
graphical animated preview of the ges- 
ture itself, with the start point in gray 
and the movement highlighted by a blue 
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point. You can see an enlarged version of this preview in a gesturetest window 
by doubl e cl i cki ng on one of the entri es: 

{ 1 P 

Test Gesture \ \ 



Draw the gesture here using the 
mouse or touch screen 




• Start point 

Close 

^^^^^^^^^^^^^^^^^^ 

Also notice that as theeditor caption points out, you are picking the gestures 
for a given target control (i n this case Forml), not at the GestureM anager com- 
ponent level. The manager has all possible gestures for the entire application, 
each form or control picks only those it is capable of handling. 

Now, having selected all of the standard gestures for the form and the panel, we 

can write some code for their generic On Ges t u r e event handler. For the panel I 

si mply log the fact the event was i ntercepted to the memo, nothi ng more: 

procedure TFor ml. Panel lGest ure( Sender : TObject; 

const Eventlnfo: TGest ur eEvent I nf o; var Handled: Boolean); 
begi n 

Log ['Panel Gesture ' ) ; 
end; 

I added this event handler to let you figure out how gestures are associated with 
the controls underneath, and what matters most is the starting position of the 
gesture as I mentioned in an earlier note. 

For gestures performed on the form, instead, I want to list some of the gesture 
information, notably their name and ID. The name is extracted from the col lec- 
tion of the corresponding component, which might not exist in case there is no 
match . H ere i s the code: 
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procedure TFor ml. For mGest ure( Sender : TObject; 

const Eventlnfo: TGestureEventl nfo; var Handled: Boolean); 
va r 

nGest ure: Integer; 

gesturel tern: TCustomGest ureCol I ectl onl tern; 
begi n 

nGesture := Eventl nfo. Gesturel D; 

gestureltem := Ge s t u r e Ma n a ge r 1 . F I n dGes t u r e ( s e I f , nGesture); 
if As signed (gestureltem) then 

Log (Format ('Gesture: %s [%d]', [ g es t u r e I t e m. Na me , nGesture]) 
else 

Log (Format ('Unrecognized gesture [%d]', [nGesture])); 
Handled : = True; 
end; 

The output of the program is a I ist of gestures performed on the form, with a 
simple indication for those originating on the panel: 



tm GesturesOl 




Gesture: SerniCirdeLeft [29] 
Gesture: SerniCirdeLeft [29] 
Gesture: Right [2] 
Gesture: Up [3] 
Panel Gesture 
Unrecognized gesture [0] 
Unrecognized gesture [0] 
Gesture: SemiCirdeRight [30] 



The Standard Gestures 

In the previous example we have enabled all of the standard gestures to the 
form and the panel, but so far I haven't given you any indication of which of 
these are predefined gestures. You can find a complete list with a graphical rep- 
resentation of each gesture i n the hel p page: 

hel p: / /embarcadero. rs2010/rad/TStandardGesture_Enum, html 

Here I've listed all of the standard gestures logically grouped (the grouping is 
mi ne) , providi ng only a few of those i mages: 

• Gestures with a single movement: Left, Right, Up, and Down. 
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• Gestures with two perpendicular movements: U pLeft, 
UpRight, DownLeft, DownRight, LeftUp, LeftDown, 
RightUp, and RightDown. There are also versions requiring 

one side to be twice as long of the other: UpLeftLong, — * 
UpRightLong, DownLeftLong, and DownRightLong (depic- 
ted here on the si de) . 

• Gestures requi ri ng two opposite movements: U pDown, DownU p, LeftRight, 
RightLeft and a repeated left and right movement, Scratchout. 

• Gestures mapped to geometrical shapes: Triangle, Square, 
Circle, and DoubleCircle. 

• Gestures with special circular movements: Semi CircleL eft, 
SemiCircleRight, Curlicue, DoubleCurli cue (shown here). 

• Gestures corresponding to two perpendicular diagonal 
movements: ChevronUp, ChevronDown, ChevronLeft, and 
ChevronRight; pi us one in which the upwards movement is twice as long 
than the downwards one, Check (shown earlier in theTest Gesture pane). 



Gestures and Actions 

Although you could usetheOnGes t u r e event handler to figure out which ges- 
ture the user performed and connect a specific operation, the gesture 
architecture of the VCL does well at tying gestures to actions. Theidea isthat 
you can issue the same command using a menu item, pressing a button, press- 
ing a shortcut key, or performi ng a gesture, and the simplest way to achieve this 
is to hook the menu item, button, shortcut, and gesture to a single action. 

I think this approach adds to the already powerful ActionM an ager architectures 
of Delphi, and its simplified ActionList sibling, making it even more the natural 
core element of most Del phi GU I s. 

In this example, called EditGestures, I have added to the main form an Action- 
List component with a couple of standard edit actions, plus a custom one: 

object ActionListl: T ActionList 
obj ect Edi tCutl: TEdi tCut 

Category = 'Edit' 

Caption = ' Cu&t ' 
end 

object Edi t Pas t el : TEdi t Pas t e 

Category = 'Edit' 

Caption = ' &Pas t e ' 
end 
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object Edit CI earl: TAct i on 

Category = 'Edit' 

Caption = ' Edi t CI earl ' 

OnExecute = Edi t CI ear lExec ut e 
end 
end 

TheOn Execute method of the custom action clears the edit box content: 

procedure TFormEdi tGest. Edi tCI earlExecutefSe 
begi n 

if (ActiveControl is TCustomEdit) then 
TCust omEdi t ( A c t i veControl ) . CI ear; 

end; 

Now while these actions can be activated using 
the shortcut commands, the program has no 
menu to execute them, but the form adds gesture 
support, connecti ng three gestures to the actions, 
as you can see i n the i mage of the Object I nspector 
here on the right. 

To have a clearer view of the actions connected to 
the active gestures for a control , what you can do 
is copy the properties of the GestureM anager 
component, which will list the gestures binding for each control connected to it 
(in this case only the form, the owner) 65 . For each active gesture you can seethe 
corresponding action: 



object Gest ur 
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TGestureManager 
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item 






Control 
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65 N oti ce that gestu re sel ecti on i s def i ned f or each control but not stored wi th the control , 
but in the centralized GestureM anager. This happens mostly because the controls can 
pul l-i n gesture data from the GestureM anager, but are unaware of the gestu res- related 
code. Were the control s aware of gestures, any appl i cati on woul d have to I i nk the gesture 
rel ated code. As the desi gn deci si on was to keep gestu re su pport outsi de of compi I ed ap- 
pl i cations that don't use it, this idea of keeping gesture data outside of the control was a 
necessary consequence. 
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item 

Act i on = Edi t CI ear 1 
GestjrelD = sgi Scratchout 
e n d > 

end> 

end 

As you can see I 've hooked the Paste action with the Check gesture, the Cut 
action with the Chevron Up ( A ), and the custom Clear action with the 
Scratchout gesture. Now, there is very little I can show you about the program 
in an image, so you'll have to test it for yourself 66 . 

There is one more thing the program does, it logs gesture operations and action 
requests, to help you better understand the flow of events. The program 
handles theOnGe 5 1 ure event of the form, which will be triggered onlyfor ges- 
tures that are not recognized or not managed. That is, if the gesture has a 
corresponding action, theOnGes t u r e event will not fire. The second hook is in 
theOn Exec u t e event of the action list, which simply logs the action name. This 
is invariably called before performing the actual action. 

Custom Gestures 

Although the list of predefined gestures is quite rich, there might be specific 
mouse movements that makesensefor your application and for specific actions 
you want users to perform. I n this cases, you can add custom gestures to the 
GestureM anager component. 

Even if you don't plan on adding custom gestures to your application, it is 
worth looking at the detai Is of this process, as it explai ns you what "matchi ng a 
gesture" exactly means and which parameters you can fine-tune to improve 
matching. 

Whi le doi ng so, we'l I also take advantage of some gestures- related components: 

• The GestureListView can be used to show a summary of the active gestures. 

• The GesturePrevi ew lets you show and test a gesture. 

• TheGestureRecorder lets your users define their own custom gestures (this 
one I won't demonstrate, as I consider it of limited practical use 67 ). 



66 Or see the proj ect vi deo, I i seed at http:// www.marcocantu .com/ dh20 10/ vi deos.htm 

67 An interesting case for custom gestures isto use it as a security measure: ask a user to 
make a gestures and then use that to recognize the user instead of asking for a password. 
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Let me start with the defi nition of a custom gesture. Place the GestureM anager 
component on a form at design time and doubleclick on it. This opens theCus- 
tom Gestures editor, featuring a list of custom gestures for the component. Of 
course, at the start of the process it wi 1 1 be empty. 

Here you can see the Custom Gestures editor after I added acustom action 
(shaped likean 8), which I've defined in the CustomGestureTest example: 



@ Custom Gestures - GestureManagerl 



23 



Name 
g eight 



ID 
■i 



Create.. 



Delete,,. 



Edit. 



Import, . , 



Export, . 



OK 



Cancel 



Help 



Now you can press the Create button to defi ne a brand new gesture. Thiswill 
open up the Custom Gesture Designer pane, in which you can graphically 
design your gesture (by dragging the mouseover the design surface) and also 
change some more global settings I ike the sensitivity or remove and insert spe- 
cific points. 

On the side of the gesture design surface, in fact, you can seethe list of points 
that make up the gesture. This is very important, as this is the actual represent- 
ation of the gesture itself: an array of points. 

What is i mportant, though, is that these poi nts are not considered as absol ute 
values, but what matters is their relative position. In practice, this means you 
can match the gesture both with an exaggerated or tight movement, but this 
movement has to be proportional to the original sequence of points. 
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Of course, a perfect match will be almost impossible, and this iswherethe 
Sensitivity factor comes into play. It determines the distance from each of the 
ori gi nal poi nts wi th i n wh i ch the gestu re repl ay poi nts must f al I . Th i s i s both a 
variation in the distance or distortion from the original sequence, and also a 
distance of fol lowi ng the poi nts i n terms of speed. I f you move too fast, too few 
poi nts wi 1 1 be recorded and they won't fit i n the area of the origi nal ones. 

I've recorded an image of the designer with a figure 7 shaped gesture below: 

@" Custom Gesture Designer 



Name: Seven Sensitivity: \j 80% [V] Unidirectional [single start point) 

Points 

X Y it 

| Q [0 □ 

4 0 

8 0 

14 0 

21 0 

27 0 

32 1 

41 1 

43 1 

55 1 

61 1 

67 1 

73 1 

79 1 

35 1 

90 1 

96 1 

102 1 

109 1 

116 1 

122 1 

127 1 

132 1 

133 1 

OK | Cancel Help 



Again, this is not easy to describe in words and you can probably figure out a lot 
of details by experi menti ng di rectly with the Custom Gesture Designer 68 . 

Notice that this 7-shaped gestu re conflicts with two others, as you can figure 
out in detail by clicking on the last icon above the designer. This opens up a list 




68 In particular, the gesture engine will use the sensitivity to rotate thegesture in case the 
gesture was drawn at a bit of an angle and it compares the angles between the gesture 
and the one drawn. Note also the unidirectional check box which let's you perform the 
gestu re al so reversed . 
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of conf I i cti ng gestures, showi ng the I i keness 
of a conf I ict for each, as you can see on the 
side. 

Now that we have added a couple of custom 
gestures to the GestureM anager, we can fig- 
ure out how they are saved i n the program. I f 
you look into the DFM file for the form, or 
copy the GestureM anager component from 
the form and paste it in an editor, you'll see 
the actual data for the gesture. This includes 
the list of custom actions with their parameters and their list of points, pi us the 
usual list of gestures enabled for each connected visual control, which includes 
both standard and custom gestures (the -1 gesture tied to Actionl, in this case): 

object GestureManagerl: TGestureManager 
CustomGestures = < 
item 

Devi at i on = 34 
Error Ma r g i n = 46 
Gesturel D = - 1 
N a me = 'eight' 

Points = {. . . actual binary data ,,,} 
end 
item 

Devi at i on = 20 

Error Ma r g i n = 20 

Gesturel D = - 2 

Name = 'Seven' 
e n d > 
GestureData = < 
item 

Control = Panel 1 

Collection = < 
item 

GesturelD = s g i Left 
end 

item 

Action = Actionl 
GesturelD = - 1 
end> 

end 

end 

Rather than be saved internally in the DFM , custom gestures can also be saved 
to an external fileand referenced from the GestureM anager, which can help 
you share the same gesture from multiple applications and edit them without 
havi ng to recompi le the program. 
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Having looked at the definition of the custom gestures and thei r storage, we 
can conti nue writi ng the code for this test appl ication. The mai n form of the 
CustomGestureTest program has a large panel used to test the gestures, the 
GestureM anager, plus a GestureListView and a GesturePreview. 

The panel handles both custom and 
standard gestures, as you can see by 
exploring the sub-properties of its To u c h 
property, which includes the two separ- 
ate I i sts, as you can see here on the si de. 

The panel manages a few gestures i n its 
On Ge s t lire event handler, whileacouple 
of them are hooked to si mple corres- 
ponding actions (PasteAction and 
Actionl): 




(TTouch Ma na g er) 
GestureMaragerl 

[eight] 

121 S Action 1 

Q7 

l;j ! . l f i* l 1 l . i;i.l ' J, . l.. g ^B E H.» ! H ! l 

US- 
IS— 

m i 
m i 
in 
or 

QJ 



procedure TCustomGestureForm. Panel lGesturef Sender: 
const Eventlnfo: TGest ur eEvent I nf o; var Handled: 
begi n 

Eventlnfo. GesturelD of 



TObj ect ; 
Bool e a n 



case 

sg 

sg 
sg 
sg 
sg 

else 

Panel 1 
end; 
end; 



Left: Panel 1. Caption : = 'Left'; 
Right: Panel 1. Caption : = 'Right 
Up: Panel 1. Caption : = 'Up'; 
Down: Panel 1. Caption : = 'Down'; 
Check: CI ose; 



Caption := IntToStr ( Event I nf o. Gest ur el D) 



Another component of the demo is the list of gestures, with averylimited pre- 
view. This is offered by the ready-to-use GestureListView control. As you drop 
it on a form at design time and connect it to 
the GestureM anager, you'll automatically 
see its list of custom gestures, as you can see 
here for the example. As you run the applic- 
ation, you'll also see the same (limited) list 
at run ti me. 

There are two ways to add standard gestures \ ± » ^ 

to the GestureListView control . One is to 
add individual gestures to the list, by calling for example: 

GestureLI stVI ewl.AddGesture(sgi Left); 




Marco Cantu, Delphi 2010 Handbook 



Chapter 6: Touch and Gestures - 179 



Another istoadd all of the gestures handled by a given target control, likein 
this case the panel: 

| GestureLi stVi ewl. AddGestures{ Panel 1); 

Of course, if you call both (as I do in the demo program) and don't clear the list, 
you'll get duplicated entries. I've left those in the demo on purpose, but in the 
real world you'll probably wantto call theCI earGestureLi st method before 
addi ng the I i st of gestures of a gi ven control . 

The last component of the demo program is a GestureP review, which lets the 

user preview entries of the connected GestureListView control, hooked to the 

Gest ureProvi der property: 

object GesturePrevi ewl: TGesturePreview 
Wi d t h = 2 5 0 

GestureProvi der = GestureLi stVi ewl 
end 



The output of the final program looks I ike the foil owing' 



,69. 




Database Gestures 



I n tryi ng to bui Id a practical example of the use of gestures, I 've decided to cre- 
ate a simple database application based on a DBG rid. My goal is to let users 
perform simple gestures (like up, down, left, and right) to move around the 
data set (performing the first, last, previous, and next actions, respectively). 



69 Again, it is very difficult to show the behavior of such an interactive application in an im- 
age: a vi deo f or thi s proj ect i s avai I abl e on the book web si te. 
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First, I created a simple application with a DBGrid, a DataSource, and a Client- 
DataSet connected one to the other: 



aSetl: TCI i entDataSet 

. \CodeGear Shared\ Data\customer, cds' 



obj ect Client Da 

F I I e N a me = 
end 

object DataSourcel: TDat aSour ce 

Dat aSet = CI i ent Dat aSet 1 
end 

obj ect DBGr i d 1 : TDBGr i d 
DataSource = DataSourcel 

Options = [dgTltles, dglndlcator, dgColLlnes, 
dgRowLines, dgRowSel ect, dgConf i r mDel et e] 

end 

Next I 've added a GestureM anager component, an ActionList component, and 
an I mageList component to the form. Remember you have to connect the 
ImageListtothel mages property of the Action List if you want to add the pre- 
defi ned i mages for the standard actions to the program. 

Now you can enable gestures for the DBGrid as usual, and customize the stand- 
ard gestures by enabling them and creati ng the proper standard actions in 
place 70 in the Object 



I nspector, as highlighted 
in this image. 

What I have done to 
obtai n this i mage was to 
expand the list of Stand- 
ard gestures, enable one 
(Left) with the check 
box, click on the drop 
down combo box, pick 
the New Standard 
Action menu item, nav- 
igate to a given category 
(Dataset), and select the 
action I was i nterested 
in (TDat aSet Fi r st ). 



Object Inspector 



DBGridl TDBGrid 
[Properties | Events I 



E 



B [Touch 
El GestureManager 
B [Gestures 
□(standard 
» Left 
Right 
Up 

Down 
UpLeft 
UpRight 
DownLeft 
DownRight 
LeftUp 
LeftDown 
RightUp 
RightDown 
UpDown 



(TTouch Manager) 
G e s tu reMa n a g e rl 

[LeftrRight.UpjDown.Check] 



New Standard Action 

^ 

on 
mr 



0 

E 
E 
E 
E 

IE 



C o .. """"is Editor.. 



[Q Messages 



TDataSetFirst 

TDataSetPrior 

TDataSetNext 

TDataSetLast 

TDataSeUnsert 

TDataSetDelete 

TDataSetEdit 

TDataSetPost 

TDataSetCancel 

TDataSetRefresh 



(No Category') 

Edit 

Format 

Help 

Window 

File 

Search 

Tab 

List 

Dialog 

Internet 

Tools 



Dataset 

DataSnap Client 



70 This technique was already mentioned inthesection "Property Editors for Actions and 
Dates" of Chapter 5. 
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I ended up picking 5 actions, four movements plus one to close the application: 

object GestureManagerl: TGestureManager 



GestureData 
item 

Control = 
Collection 
item 
Action 



DBGr I dl 
= < 



DataSetPri orl 
GesturelD = s g i Left 
end 
item 

Action = Da t a Set Next 1 
GesturelD = sglRlght 

end 

item 

Action = DataSetFirstl 
GesturelD = sgiUp 

end 

item 

Act I on = Dat aSet Last 1 
GesturelD = s g I Down 

end 

item 

Action = FlleExltl 
GesturelD = s g i Check 
end> 



e n d > 



end 



fly Object Inspector 




ToolButtonG TToolButton 




| Properties | Events | 



Next I added a Tool bar control to the 
application, created five buttons, hooked 
the exi sti ng acti ons to the tool bar but- 
tons (using the Object I nspector as in 
the i mage here on the ri ght) . 

To let users perform the actions on the 
toolbar area as well, I also added the 
same gestures of the DBGrid to the 
form. With the tool bar not having ges- 
ture support, the corresponding 
operations will be sent to the control or window behind it. 

Finally,! added anOpen call for the CI ientDataSet control in theOnCr eat e 
event handler of the form, and I had a running application with basically no 
Delphi code behind it. Run the program, perform a "down" gesture, and the 
DBGrid will jump to the last record, as shown i n the i mage of the next page. 



Action 

AlignWithMargi 

Allow AllUp 

AutoSize 

Caption 

Cursor 

CustomHint 

Down 

DragCursor 

DragKind 

DragMode 



New Action 

New Standard Action 


► 


M DataSetf irstl 




M DataSetlastl 




► DataSetNextl 




* DataSetPrior 1 




JLFileExitl 


"roKorng 

drnManual 
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Data Gestures 
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6812 Waterspout SCUBA Center 
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9841 Neptune's Trident Supply 
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This program has a significant problem, though. As you perform any gesture 
over the grid, it also receives regular mouse messages and selects the record 
under a mouse click. So if you do a "right" gesture, you'll click and select the 
record under the mouse and also perform the gesture and move to the next 
record. This is not very intuitive. If you perform the gestures in the thin toolbar 
area, everythi ng works as expected. 

For a touch enabled application, though, we might want to disable the standard 
"click-to- select" grid operation, to force users to perform gestures (or use tool- 
bar buttons) to move around the data. This can be achieved by disabling the 
mouse operations on the grid. 

The si mplest way to do thi s i s to subcl ass the gri d ( usi ng an i nterceptor cl ass) 
and return False from theFoc used virtual method, indirectly called at the 
beginning of each mouse operation. This is the code (avail able in theDataGes- 
tures example, but commented out in the source) you can use: 
type 

TDBGri d = cl ass ( DBGri ds. TDBGri d) 
public 

function Focused: Boolean; override; 
end; 

function TDBGri d. Focused: Boolean; 
begi n 

Result : = Fal se; 
end; 
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Touch Keyboard 

When you are creating applications for kiosks and other devices which don't 
have a keyboard attached, it isnicetoshowoneon screen and let users type by 
selecting these keys with their input device (possibly their finger, as using a vir- 
tual keyboard with the mouse is far from a nice experience). 

TheVCL in Delphi 2010 includes a framework for creating virtual keyboards, 
based on the newTouchKeyboard component and the two related units, Key- 
board and KeyboardTypes. If you drop the Touch Keyboard component on a 
form at design time you'll see something I ike in the foil owing image: 




Of course, what you'll see depends on your active keyboard at the operating sys- 
tem level . What I 've shown here is the output when I set the keyboard to "en- 
US". If I keep my standard settings, I'll generally see an Italian keyboard: 



© Forml | o | |Hn i ~5~| 




\- iii'^i-JU i[ - 1 iillriii' -I'liinlln 1 
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El[KeyCaptions 








Backspace 




Tab 




Del 




Caps 




Enter 




LeftShift 




RightShift 




LeftCtrl 




LeftAlt 




RightAlt 




RighKtrl 



Notice that while punctuation characters are 3|Ke y ca P tions 
indeed replaced by the corresponding elements in 
Italian, special purpose keys (like Esc, Caps, Del) 
are not modified. The issue is that the captions of 
these keys are not def i ned at the operati ng sys- 
tem, so the only option is to override the defaults 
at the Touch Keyboard component level, using its 
KeyCapt i o n s property you can use to change 
individual captions, as shown here. 

Another key property of the component is its ability to display a numeric 
keypad (likethe one on the right) rather than afull keyboard, by changing the 
value of theLayout property (a string, not an enumera- 
tion, to allow future expansion and custom keyboard 
layouts) from Standard to Keypad 71 . 

Regardless of the layout, the effect of usi ng this vi rtual 
keyboard is to send i nput to the control currently havi ng 
the input focus, I ike a physical keyboard. Of course, this 
means that the button representi ng keys won't get the 
focus when pressed, preserving the current input focus. You can seethiseffect 
in the basic KeyboardTest application (here when holding the Shift key): 





m.atwa 


a 6 




-JL-*. 



4g KeyboardTest 



Labeled Ed itl 
one= 1 



Labeled Edit2 



two = 2| 



Test 



Esc ~ 
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Del 

















71 You can create custom layouts, as Chris Bensen started explaining on his blog in the post 
http:// chrisbensen.blogspot.com/ 2009/ 12/ hacking-ttouchkeyboard-part-i .html and in 
the following 3 parts, showing also how to create a custom layout from an XML repres- 
entation of the keyboard. 



Marco Cantu, Delphi 2010 Handbook 



Chapter 6: Touch and Gestures - 185 

The program also has a button that I 've used to make a few experi merits and try 
to fi nd a workaround to an annoyi ng VCL problem. As soon as I run a standard 
VCL application (including Delphi itself) it will reset my current keyboard to 
the default one. So whatever my keyboard setting a Delphi application will start 
with the Italian keyboard 72 . 

I n the button I 've made two experi ments, as you can see I the code below: 

procedure TKeyboardForm. btnTestCI i ck( Sender: TObject); 
var 

code: Ul NT; 
begi n 

Loa dKey boardLayout ('00000409', KLF_ACTI VATE) ; 

code : = MapVi rt u a I Key ( 43, MA P V K_ VS C_ T 0_ V K ) ; 
ShowMessage ( I ntToSt r ( code) ) ; 
end; 

Fi rst, I write the code need to force a different keyboard, specifi cally the 'en- 
US' keyboard, which has the keyboard layout code '00000409'. Loading and 
activating this layout broadcasts a wm_ I nput LanguageChange, which the 
TouchKeyboard component handles updating its layout. As an alternative you 
can call the Ac t i vateKeyboardLayout function and Redraw the touch key- 
board after letti ng the appl ication process update messages: 

Acti vateKeyboardLayout( 67699721 {en-US}, 0); 
Appl i cat i on. Process Me s s ages ; 
Touch Keyboardl. Redraw; 

Second, I use the same code of the TouchKeyboard component for converting a 
virtual key into an actual character code, as an experiment. I used this code to 
f i gu re out the VCL i ssue descri bed earl i er . 

Overall the TouchKeyboard component can be handy in a kiosk or similar 
application, while in other occasions you might want to hide it and display it on 
request. Of course, you'll always need to have it on screen only while the user 
has to i nput some data, or you can prepare a standard "keyboard entry form" 
with a single edit box and a keyboard you show every time there is an input 
request (I ike when the actual edit in the main form received the focus). I've not 
created a demo program showi ng a si mi I ar si tuati on , but i t shoul dn 't be terr i bl y 
difficult to create one. 



72 The situation is actually worse, as running a Delphi program changes the active keyboard 
at the operating system setting, that is for each running application. Quite annoying, al- 
though few people use multiplesettings. 
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Multi-Touch Support 

As I detailed in the section "From SingleTouch to Multi-Touch", Windows 7 
and Delphi 2010 have specific support for multi-touch hardware, basically in 
the form of a new Windows message (wm_ touch) and support for handling it at 
theVCL level. Considering the current limited crop of multi-touch enabled 
hardware, though, this support should probably be restricted to specific applic- 
ations for quite some ti me. This is why the coverage of native touch, or 
wm_ t o uc h , in this chapter is restricted to this section and based on an example 
I 've borrowed from Chris Bensen 73 . 

Before we get specifi cally to wm_ t o u c h , consider that some i nformation about 

touch-based requests is also surfaced in traditional mouse events. Pressing on 

the screen (or touchpad) with your finger results in a VCL mousedown event, 

carrying over information about the source. This is provided in the 

Shi f t S t a t e parameter of mouse events, as theT Shi f t S t a t e enumeration 

has been extended with two new elements, touch and pen. The enumeration in 

Delphi 2010 has the foil owing values: 

I TShi f tState = set of (ssShi ft, ssAI t, ssCtrl , 

ssLeft, ssRight, ssMiddle, ssDouble, ssTouch, ssPen); 

This is relevant because you might want to handle touch operations like mouse 
operations, providing limited extra information. On the other hand, if you are 
specifically handling touch operations, you might want to disable any mouse 
request comi ng from a touch source, or you'll handle the request twice (the first 
ti me as a native touch request, and the second ti me as a mouse operation ori- 
gi nati ng from the touch request) . 

Handling wm touch 

Thewm_ touch message is a raw, low-level Windows message, providing a sig- 
nificant amount of information about the user input (unlike a mouse message). 
Considering the limited data a Windows message can carry, this is actually not 
a precise description. 



73 Chris is a Delphi R&D member who worked on touch support in Delphi 2010. Hisblog is 
at http://chrisbensen.blogspot.com/ . I got permission from him to quote the source code 
of this demo appl ication i n my book. 
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What you recei ve i n the message's L P a r a m is the handle of a touch i information 
data structure you can retrieve by calling the Get Touchl nput I n f o API func- 
tion. Before you call this fundi on, you must allocate the proper amount of 
memory for the array of touch points, using the number of points that iscarried 
i n the WP a r a m of the message. At the end, you must release the touch i nforma- 
tion data structure by calling the CI oseTouchl nput Handl e API function. 

H ere is how the standard wm_ To u c h handl i ng code looks I i ke: 

// in the TMyForm class declaration 

procedure WMTouchfvar Message: TMessage); message wm_Touch; 

procedure TMyFor m, WMTouchf var Message: TMessage); 
var 

Touchlnputs: array of TTouchl nput; 
Touchl nput: TTouchl nput; 
begi n 

Set Lengt h (Touchlnputs, Message. WParam); 
GetTouchl nputl nfo ( Message. LParam, Message. WParam, 

@Touc hi nput s [ 0] , Si zeOf ( TTouc hi nput ) ) ; 
for Touc hi nput in Touchlnputs do 

CI oseTouchl nput Handl e ( Me s s a g e . LParam); 
end; 

Each Touchl nput element of the array is a record with the i nformation about 
the touch position (x and y ) in "hundredths of a pixel of physical screen 
coordinates" 74 , a handle to the input device, an IDof the touch point(which 
remai ns the same over ti me whi I e the user keeps pressi ng or movi ng a f i nger) , 
several flags indi eating the current operation for the touch point (up, down, 
move, and soon), the time stamp of the operation, the horizontal and vertical 
size of the touch or contact area: 
type 

TOUCHI NPUT = record 

x : Integer; 

y : Integer; 

hSource: THandle; 

dwID: DWORD; 

dwFlags: DWORD; 

dwMask: DWORD; 

dwTi me: DWORD; 

dwExt ral nfo: ULONG PTR; 

cxContact: DWORD; 

cyContact: DWORD; 
end; 



74 According to M icrosoft's SDK documentation for the data structure at: 
http://msdn.microsoft.com/en-us/library/dd317334.aspx 
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To manage and interpret the x andy coordinates, you might want to call the 
P h y s i cal ToLogi cal Poi nt Windows API function to convert the physical 
screen location to the logical coordinates the application understands. 

To receive this information, as mentioned, you need to have multi-touch 

enabled hardware, but the application must also register individual windows to 

receive touch messages by calling the Re g i sterTouchWi ndow API function. 

You'll makethiscall after the form handle has been created, for example in an 

overridden version of theC r e a t e Wn d method: 

procedure T My Form. FormCreate (Sender: T Object); 
begi n 

inherited; 

RegisterTouch Window! Handle, 0); 
end; 

Remember to also unregister the window for touch, once you've finished with 
it, by cal ling the symmetric API function Un r eg i st erTouchWi ndow 75 . 

Chris Bensen's TouchMove Demo 

To demonstrate touch support in Delphi 2010, along with Direct2D support 
(that I covered in the last chapter) and inertia manipulations (that I 'II cover in 
the next section), ChrisBensen wrote a very nice demo cal led TouchMove, 
which I decided to refer to in this section. I won't cover other elements of the 
demo, only how it manages touch 76 . The demo handles a number of touch 
poi nts at the same ti me, creati ng for each a "gl ow spot" element or usi ng an 
existing one if the touch operation was performed on active spot. 

For doing any point- based manipulation, the code uses a support function 

(TouchPoi ntToPoi nt)to convert the coordi nates of the touch poi nts from 

hundredths of a pixel to pixels and from device- based poi nts to logical points: 

(function Touc hPoi nt ToPoi nt ( const TouchPoint: TTouc hi nput ) : TPoint; 
begi n 

Result := P o i n t ( To u c h Po i n t , X div 100, TouchPoint. Y div 100); 
Physi calToLogi cal Poi n t ( H a n d I e, Resul t); 
end; 



75 Unregistering touch windows on termination is nice, but doesn't seem to be required. Ac- 
cording to M DSN documentation, you should callUnregi sterTouchWi ndow to indic- 
ate that a window "no longer requires touch input". That's all. 

76 For the links to hisfour-part description of the TouchMove demo see Chris' summary 
post see http://chrisbensen.blogspot.com/ 2009/ HJ touch-demo.html 
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Thecoreof the program is in hiswmt ouch message handler. 

procedure TTouchForm. WMT o u c h ( v a r Message: TMessage); 
va r 

Touchlnputs: array of TTouchlnput; 
Touchlnput: TTouchlnput; 
Handled: Boolean; 
Point: TPol nt ; 

TouchMessage: TTo uc h Mes s a g e ; 
begi n 

Handl ed : = False; 

Set Lengt h( Touchl nputs, Message. WParam) ; 
GetTouchl nputl nfo( Message. LParam, Message. WParam, 

@Touc hi nput s [ 0] , SI zeOf ( TTouc hi nput ) ) ; 
try 

for Touchlnput in Touchlnputs do 
begi n 

Point := To uc h P o i n t To P o I n t ( To u c h I n p u t ) ; 

if (Touchl nput. dwFI ags and TOUCHEVENTF_ MOVE) <> 0 then 

Touch Me ssage : = t mMo ve 
else if (Touchl nput. dwFI ags and T OU C H E V E N T F _ U P ) <> 0 then 

TouchMessage : = t mUp 
else if (Touchl nput. dwFI ags and T OU C H E V E N T F _ DOWN ) <> 0 then 

Touch Me ssage : = t mDo wn ; 
P r o c e s s To uc h Mes s a ge s ( P o I n t , Touchl nput.dwl D, TouchMessage); 
end; 

Handled : = True; 
finally 

if Handl ed t hen 

CI oseTouchl nput Handl e ( Me ssage. LParam) 
else 

i nher i ted; 

end; 
end; 

As you can see in the WMT o uc h method, the code grabs information about the 
touch operations picking a value out of theTTo u chMessage enumeration, 
which islater passed to the ProcessTouchMessages method. The goal isto 
use the same processing function, as for mouse operations (which are pro- 
cessed only if they didn't originate from a touch action, to avoid any double 
processing), asforexampleintheOnMouseDown handler: 

procedure TTouchForm. For mMo useDown( Sender : TObject; 

Button: T Mo us e But t o n ; Shift: TShiftState; X, Y: Integer); 
begi n 

if ssTouc h in Shift then 
Exit; 

F Mo us e Do wn : = True; 

P r o c e s s To uc h Mes s a ge s ( Po i n t ( X, Y) , 0, tmDown); 
end; 

I n this case there is no need to convert the coordi nates, as they are exactly what 
the program expects. Finally, thePr ocessTouchMessages method looks for 
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an existing glow spot with the given ID or one at the given location, and if none 

is found creates a new one: 

function TTouc h Fo r m. P r oc es s To uc h Me s s ages ( cons t APoint: TPoint; 

ID: Integer; To uc h Mes s a g e : TTo uc h Mes s a ge ) : TGI owSpot; 
va r 

Spot : TGI owSpot ; 
begi n 

Result : = ni I ; 

Spot : = Fi ndSpotf ID); // find by ID 
if Spot = nil then 
begi n 

Spot := F I n d S po t ( AP o I n t ) ; // find by location 
if Spot <> ni I then 
Spot . I D : = ID; 

end; 

if Spot = nil then // create a new one 
begi n 

Spot := TGI owSpot. Create(Sel f); 
Spot . I D : = ID; 
FSpot s, Ad d ( Spot ) ; 
end; 

Spot . DoTouc h( APol nt , ID, To u c h Me s s a g e ) ; 
Result : = Spot ; 
end; 

Again, thereismuch more to this demo, of which I didn't display any images as 
they are very hard to capture on paper. The complete source code of Touch- 
Move example is included in the book source code and it is also avail able at the 
original download location: 

h 1 1 p : / / c c . e mb a r c a d e r o . c o m/ 1 tem/ 27469 

Inertia Manipulation (with no 
Touch) 

The demo by Chris Bensen makes a very i nteresti ng use of the M ani pulations 
and I nertia engine that's built into Windows 7 and surfaced in corresponding 
Delphi API interface units. This engine is based on COM, and isreadytouse 
from Delphi applications. All you have to do is to figure out how, and most of 
the avail able demos are quite complex. So I 've decided to write a program spe- 
cifically focused on using the I nertia support, with no touch, no Direct2D, and 
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no other features that would distract you. All this program does is show a ball 
(a colored circle) and lets you move, throw it... and see it bounce. 

Atthecoreof thelnertiaBall examplethereisaTBal I class representing a 
singleobject (I haven't extended the application to handle multiple objects at 
once to keep it as simple as possible). Internally this class uses the inertia pro- 
cessor and the manipulation processor provided by Windows 7, and 
implements a specific manipulations interface, used as a call back to notify 
changes in the position of the object. 

• The manipulation processor lets you interact with a physical object rep- 
resented on the screen i n a more real i sti c way and gi ves access to i ts status. 
For example, by asking the manipulation processor to change the position of 
an object we'l I be able to ask for the current speed of the object. 

• The inertia processor lets you implement a realistic behavior for an 
object, like keep it moving at its current speed, slowed down by its natural 
i nerti a, or let it bounce agai nst the borders of a surface. 

For more information on these two COM objects available in Windows 7 and 
their interfaces (available in Delphi 2010 in the Manipulations unit), you can 
refer to the API documentation on the M SDN site at: 

h 1 1 p : / / msdn. microsoft, co m/en-us/l i brary/dd372613.aspx 

After this short introduction, this is the declaration of the class representing a 
bouncing ball: 

uses 

Ma n i p u I at i ons ; 
type 

TBall = class ( T I n t e r f a c ed Obj e c t , I Ma ni pul ati onEvents) 
pr i vat e 

F I nerti a : I I nerti aProcessor; 

FMani pulator: I Ma n i pul ati onProcessor; 

As the program creates an object of this class (which happens as the mai n form 

is itself created), it creates the two COM objects, sets the interface of the object 

as a response to the COM object events (handling the J Ma n i pul ati onEvent s 

interface), and initializes a few properties of the inertia manipulator: 

constructor TBall. Create (aForm: TForm); 
begi n 

inherited Create; 

ID : = 1; 

FCompleted : = True; 

F I nerti a := Creat eCo mO bj ect(CLSI D_l I nerti aProcessor) 

as I I nerti aProcessor; 
FManlpulator := Creat eCo mO bj ect(CLSI D_l Mani pul ati onProcessor) 

as I Mani pul ati onProcessor; 
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I nterfaceConnect( Fl nerti a, 
Self, Fl nerti aCooki e) ; 

I nterfaceConnectf FMani p u I ator 
Self, FMani pul atorCooki e); 



I Ma n i pul atl onEvents, 

I Ma n i pul atl onEvents, 



en 



n e r t 
n e r t 
n e r t 
n e r t 
n e r t 
n e r t 
n e r t 
n e r t 
n e r t 



put 
put 
put 
put 
put 
put 
put 
put 
put 



Desi redDecel e r a 1 1 o n ( 0 . 0 0 1 ) 
BoundaryLef t ( 200) ; 
^BoundaryTopf 2 0 0 ) ; 
BoundaryRi g h t ( a F o r m. 



BoundaryBot 



El ast 
El ast 
El ast 
El ast 



c Ma r g 
c Ma r g 
c Ma r g 
c Ma r g 



dth - 
omfaForm. Height 
nLef t ( 100) ; 
nTop( 100) ; 
n R i ght ( 100) ; 
nBot t om( 100) ; 



2 0 0) ; 
- 2 0 0) 



As you can seethe movements boundary (called Boundary in the image) is set 
at 200 pixels within the border of the form. However, half of this area (100 
pixels all around) is actually used as an elastic, bouncing area (called Elastic 
Margin in the image). Outside of this margin (which is external to the bound- 
ary) there is an area the object will never reach 77 , which is 100 pixels wide. The 
three areas are depicted i n the i mage of the next page, which is an actual i mage 
of the program from which I 've removed the bounci ng bal I . 



r j| Inetirtall 



a 



Elastic Margin 



Boundary 



77 The obj ect wi 1 1 never reach the area after you thr ow i t, but the program doesn 't prevent 
you from dragging it to this external area... 
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As I mentioned, theTBa I I object is created in the middle of the form as the 

program starts (after tweaking the division by zero system exception 78 ): 

procedure Tl ne r t i a Fo r m. Fo r mCr ea t e ( Sende r : TObject); 
begi n 

// disable di v by 0 exceptions for the inertia processor 
Set 8 0 8 7 CW( $ 1 3 3 F ) ; 



a Ba 
a Ba 
a Ba 
a Ba 
a Ba 
a Ba 
end; 



: = T B a I I . Create ( sel f 
X : = Wi d t h d i v 2 ; 
Y : = Hei ght di v 2; 
Radius : = 20; 
Color : = c I Red; 
ID : = 1; 



The ball is painted on the screen along with the two focus rectangles in the 

On P a i nt event handler of the form: 

procedure Tl nerti aForm. FormPai nt( Sender: TObject); 
begi n 

aBal I . Pai nt(Canvas) ; 
DrawFocusRect ( Canvas. Handl e, 

Rect ( 1 0 0, 1 0 0, Wi dt h- 100, He i g h t - 1 0 0 ) ) ; 
DrawFocusRect ( Canvas. Handl e, 

Rect ( 2 0 0, 2 0 0, Wi dth- 2 0 0, Hei ght- 2 0 0 ) ) ; 

end; 

The actual painting of the ball is quite trivial: 

procedure T B a I I . Pa i n t ( Ca n va s : TCanvas); 
begi n 

Canvas. Brush. Col or := self. Color; 

Canvas. El I i pse(x-Radi us, y-radius, x+radius, y+radius); 
end; 

Things start getting interesting as you move the mouse. I n this case rather than 
changing the ball position directly, the program changes it via the manipulation 
processor, which will notify the ball using the call back events of the 
J Ma n i pul ati onEvents interface. The three manipulation operations take 
place as the user presses the mouse button, moves the mouse, and releases it. 
Each of these three events at the form level cal Is a correspondi ng event of the 
ball object, which calls a corresponding method of the manipulation processor. 
It is worth following each of them, to understand the temporal sequence (as it 
took me a wh i I e to f i gu re i t out) . 



78 If you don't disable the div by zero exception, theinertia processor will indeed throw 
them quite often, as you can easily figure out by commenting out that line of code and 
running the program. Howdid I find out? By looking at the Inertia processing demos 
from M SDN , after hitti ng way too many errors with my code. 
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The first operation is a mousedown at the form, ball, and manipulation man- 
ager level: 

procedure Tl nerti aForm. For mMo useDown( Sender : TObject; 

Button: T Mo us e B u 1 1 o n ; Shift: TShiftState; X, Y: Integer); 
begi n 

a B a I I . MouseDownf X, Y) ; 
Invalidate; 
F Mo us e Do wn : = True; 
end; 

procedure T B a I I , MouseDownf X, Y: Integer); 
begi n 

F Ma n i p u I a t o r . P r oc es s Do wn ( I D, X, Y) ; 
end; 

The program wi 1 1 receive several mouse move events: 

procedure Tl nerti aForm. For mMo useMove( Sender : TObject; 

Shift: TShiftState; X, Y: Integer); 
begi n 

if FMouseDown then 

begi n 

a B a I I . MouseMovef X, Y) ; 
Invalidate; 
end; 
end; 

procedure T B a I I . MouseMovef X, Y: Integer); 
begi n 

F Ma n i p u I a t o r . P r oc es s Mo v e ( I D, X, Y) ; 
end; 

Thelast (and most important) operation isthe mouse up. Attheend of this 

manipulation, in fact, the program starts the inertia processor: 

procedure Tl nerti aForm. For mMo useUp( Sender : TObject; 

Button: T Mo us e B u 1 1 o n ; Shift: TShiftState; X, Y: Integer); 
begi n 

a B a I I . MouseUp (X, Y) ; 
F Mo us e Do wn : = False; 
Invalidate; 

Ti me r 1 . Enabled : = True; 
end; 

procedure TBall.MouseUpfX, Y: Integer); 
va r 

vx, vy: Single; 
begi n 

FMani pul ator. ProcessUpf I D, X, Y) ; 

FMani pul ator, GetVel oci tyX(Vx); 
FMani pul ator. GetVel oci tyY(Vy); 
Fl nerti a. p u t _ I ni ti al Vel oci tyX(Vx) ; 
Fl nerti a. p u t _ I ni ti al Vel oci tyY(Vy) ; 



Marco Cantu, Delphi 2010 Handbook 



Chapter 6: Touch and Gestures - 195 



Fl nerti a. put_l ni ti al Ori gi nX(X) ; 
Fl nerti a. put_l ni ti al Ori gi nY(Y) ; 

FCompleted : = False; 
end; 

The inertia processor doesn't do much on its own. You have to ask it often to 
process its status (which is clearly time dependent), for example using a timer: 

procedure TI nerti aForm. Ti merlTi mer( Sender: T Object); 
begi n 

a B a I I . Processl nerti a; 
Invalidate; 
end; 

procedure TBal I . Processl nerti a; 
begi n 

if not FCompleted then 

Fl nerti a. Process(FCompl eted); 

end; 

Each time the manipulation or inertia processors compute a new position for 
the object, they notify it via the Man i pul at i onDel t a method of the 
_ I Ma n i pul ati onEvents i nterface: 

function TBal I , Mani pul at I onDel t a( X, Y, 

translation DeltaX, translation Del t a Y , 

scale De I t a , expansl onDel t a, r o t a 1 1 on De I t a , 

cumul ati veTransI ati onX, cumul ati veTransI ati onY, 

cumul ati veScal e, cumul ati veExpansi on, 

cumul ati veRotati on: Single): HRESULT; 
begi n 

sel f . X : = Round ( X) ; 
sel f . Y : = Round ( Y) ; 
Resul t : = S _ OK; 
end; 

Notice that all manipulations and inertia information usesSi ngl e coordinates 
for much better precision 79 , which is why these examples are better built using 
theDirect2D output and its floating point coordinates, but again I wanted to 
keep this as simple as possible, so I used a traditional GDI painting surface. 

The result cannot be easi ly depicted i n a static i mage, although you can see one 
in the next page, and can be appreciated much better by running the program 80 . 



79 In a first tentative attempt, I added to the current X position thet ransl ati onDel taX, 
but round i ng this val ue it soon got down to zero, practical ly stoppi ng the operation wel I 
before it was done. 

80 Or by looking at the project video, again available on the book web site. 
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What's Next 



This chapter ends the section of the book covering the VCL and Windows 7. We 
have discussed many new Windows 7 APIs, some of the corresponding new 
VCL controls, and other new features of the VCL which are only partially 
related to Windows 7 and will also work perfectly on older versions of Win- 
dows, I ike gestures. 

I n the I ast two chapters of the book, I 'I I focus on Database support, mostly i n 
multi-tier and Web applications based on the REST protocol. The main focus of 
the two chapters, i n fact, i s to cover new extensi ons of the DataSnap engi ne, 
although there is also some coverage of the dbExpress framework and of other 
data access technologies that Delphi 2010 provides. 
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Chapter 7: 
Database Access 
And DataSnap 



The development of database-oriented applications, with stand-alone, 
client/ server, or multi-tier architectures, has always been one Delphi's strong 
features. 1 1 is not surprisi ng that this version bri ngs i ncremental new features 
to the database area of the product. 

While Delphi 2007 introduced a new generation of dbExpress (called dbEx- 
press I V) and Delphi 2009 brought us a new generation of DataSnap (often 
referred to as DataSnap 2009), Delphi 2010 provides incremental features in 
both areas. Specifically regardi ng the DataSnap multi-tier model, this version 
completes the new architecture that we could say was only partially available in 
Delphi 2009. New features include HTTP support, callbacks, filtering with 
compression and encryption, and REST interfaces. 

Notice that if you've never used these two technologies (dbExpress and Data- 
Snap) you won't f i nd i ntroductory materi al here, but mostly a focus on what's 
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new in Delphi 2010. Consider also that DataSnap and the complete versions of 
dbExpress, with all new drivers and connectivity to remote databases, are avail- 
able only in the Enterprise and Architect versions of Delphi. 

However, before I cover these two main features, let me touch on a few other 
interesting new elements of Del phi's database architecture. 



New Field Types and Other Core 
Database Extensions 

Although the enhancements to the overall Delphi database architecture can be 
considered as mi nor, the new features that have been introduced will have a 
very significant impact for some developers. For example, for managing float- 
ing point numbers with a limited representation and time stamp offsets, there 
are specific T Field -derived classes that you can now use: 

TSingleField = cl ass(TNumeri cFi el d) 

TSQLTi meStampOf f set Fi el d = c I a s s ( T SQLT i me S t a mp F i e I d ) 

Support for time stamp offset processing is now also available in the new 
TSQLTi meSt ampOf f set class that's been added to the SqlTimSt unit. 

Matching these two new field types, plustheTObj ectFi el d types now used by 
DataSnap, thereare three new elements in theTF i el dType enumeration: 
ftTi meStampOffset, ftObject, and ftSingle. 

Also, i n theT F i el d class you can convert the val ue of the current element 

usi ng some new As properties: 

property AsSQLTi meStampOffset: TSQLTi meSt a mpOf f s et ... 
property As Single: Single ... 
| property AsLargel nt : Largeint ... 

Corresponding As properties have been added to theT P a r a m class. Given the 
newfield classes introduced in Delphi 2010, the hierarchy of theTF i el d 
classes defined in theDB unit becomes even bigger. 

To hel p you get a f ul I pi dure, I 've provi ded a compl ete cl ass tree i n the fol I ow- 
ing page (with new classes introduced in Delphi 2010 marked in bold). 
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TFi el d 

TSt r i n g F i el d 

TWI deStrl n g F i el d 
T G u i d F i el d 
TNumeri cFI el d 
Tl ntegerFI el d 
TAutol ncFI el d 
T 5 ma I I I n t F I e I d 
TShorti ntFi el d 
TByteFi el d 
T Wo r d F i e I d 
TLongWordFI el d 

TUnsi gnedAutol ncFI el d 
TLargel ntFi el d // I nt 64 
TFI oat Fi el d 

TCur r encyFi el d 
TExt endedFi el d 
TBCDFi el d 
TFMTBCDFi el d 
TSi ngl e F i el d 
TBool eanFi el d 
T Da t e T i me F i el d 
T Da t e F i el d 
T T i me F i el d 
TSQLTi meStampFi el d 

TSQLTi meSt ampOf f s et F i el d 
TBi naryFi el d 
TBytesFi el d 
TVarBytesFi el d 
TBI o b F i el d 
T Me mo F i el d 

T Wi d e Me mo F i el d // widest ring memo 

TGr a p hi c F i el d 
TObj ect Fi el d 

TADTField // Abstract Data Type 

T Ar r a y F i el d 

TDataSetFi el d 

TReferenceFi el d 
TVari antFi el d 
Tl nterfaceFi el d 

Tl Di spatchFi el d 
TAggregateFi el d 

There are some other changes focused on very specific needs, I i ke local depend- 
ent stri ng formatti ng for date and ti me fundi ons, the remappi ng of 64- bit 
i ntegers to the I nt64 rather than BCD, and other similar changes probably not 
worth covering in detail. 
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Themes Support and Other DBGrid Extensions 

Even with the stronger themes support 
already in the VCL for a couple of ver- 
sions (introduced in Delphi 7, but much 
expanded in Delphi 2007), not all of the 
visual controls got full themes support. 
A notable absence was in the VCL grids, 
both the plain ones (StringGrid and 
DrawGrid) and the data- aware version 
(DBGrid). This has now been addressed. 

I n the i mage on the si de you can see the 
same application (DbxMulti2010, the 
new version of asimpledbExpress 
demo I used in previous books) with 
and without themes enabled. The differ- 
ence i s quite stri ki ng, as with minimal 
user i nterface changes the output looks 
more modern. 

I n case you don't want to use this new 
user i nterface style and sti 1 1 have the 
application themed, you can use the 
Dr awi n g 5 1 y I e property, which is set to 
g d 5 T h e me d by default but can be 
switched back to g d s C I a s s i c or the 
alternativegds Gr adi ent .Along with the new gradient style, thegrid controls 
have a G r adi ent St art Col or and a G r adi ent EndCol or property. 

As an aside, the DBGrid control has two new options, dgTi 1 1 e C I i c k and 
dgTi tl eHotTrack. ThedgTi 1 1 eCl i c k option lets you control whether the 
user can cl i ck on the title (eventual ly disabl i ng the correspondi ng graphical 
effect). When thisoption isdisabled, theOn T i tl eCl i ck event won't fire, of 
course. Now the problem is that if you create a brand new application the 
dgTi tl eCl i ck option is enabled by default. While for an existing application 
opened in Delphi 2010, it will be set to False as it was not in among the flags in 
the original DFM file. I guess they could have entered an option with the 
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opposite meani ng (disable title cl ick) to preserve compati bi I ity, but it would 
have looked quite awkward 81 . 



DBGrid In-place Editor Issues 
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The problem with any version of the Dr a wi ngStyl e property is that as the 
DBGrid displays the in-place editor, it draws a thick black border around it. In 
effect, that's not a bl ack border but the wi n- 
dow background color, which is managed in 
a different way from the past. You can see 
the effect i n the i mage here on the ri ght. 

How can we fix the problem 82 ? The issue is 
rooted deep i n the i nternal pai nti ng code, 
which is extremely complex. There wasn't a 
si ngle specific fix that caused this unwanted effect, but a set of changes related 
with themes support. The problem occurs for any themed application, as the 
issue shows up regardless of the value of the Dr a wi ngStyl e property. We can- 
not even handletheOn Dr a wDat a Ce I I event of theDBGrid, as for cells under 
the in-place editor it doesn't get called. So we have to resort to a changing the 
internal behavior of theDBGrid and itsTCust omGr i d ancestor class. 

I noticed that if we let theP a i nt method of theTCus t o mGr i d class paint the 
specific eel I i n the same way it does for any other cell , the problem disappears. 
Foratest, you can copy the Grids unit to a project; inside that Pai nt method 
you'll find the internal DrawCel I s subroutine (starting at line 2150); locate the 
test which determines if standard painting code is executed (at line 2186); 
you'll see the foil owing: 



if not ( gdFocused in Dr a wS t a t e ) or not 

not FEdi t or Mode or (csDesigning in Component St at e 



goEditing in Options) 
then 



or 



If you comment out this code, the grid behavior will get back to normal . How- 
ever, I don't particularly likechanging VCL units, so I tried looking for an 
alternative fix. Theidea isthat if we make the test above succeed, standard 



81 The problems with the dgTitleClick option were first reported by Bob Swart on his blog at 
http://www.bobswart.nl/ Weblog/ Blog.aspx?Rootld=5:3791 

82 I reported this bug (or significant change in behavior) on Quality Central and it is avail- 
abl e at http:/ / qc.embarcadero.com/ wc/ qcmai n.aspx?d =80209 
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painting will take pi ace also for the eel I showing the in-place editor, and its 
background (visible only for the portion around the editor) will change from 
black to white or whatever is the correct color. 

Armed wi th the i dea and consi deri ng that code i s cal I ed i nsi de the Paint 
method, I decided to override it. As it is a virtual function, you cannot use a 
class helper, but you can use an interposer class 83 . 1 n this case, I 've written a 
new unit with the foil owing interface: 

unit DbGr i d F i x; 

i interface 

uses 

DBGr ids; 

type 

TDBGri d = cl ass ( DbGri ds. TDBGri d) 
protected 

procedure Paint; override; 
end; 

As long as the unit is i ncl uded after the DBGrids unit i n any form that uses a 
DBG rid component, the compiler will refer to this version of theT DBGr i d class 
rather than the official one. This means at design time you'll be using a stand- 
ard DBGrid, whileat run ti me the component isfully replaced by the version 
defined in theDbGridFix unit. 

Inside the Paint method what we can do isto temporarily change the value of 
the F E d i tor Mode field, which determines the different behavior for the 
repai nti ng of the area behind the in-place editor. This field is not used any- 
where else i n the pai nti ng code, so we should not cause any other problems. 
However, if wesettheEd i t or Mode property, this will cause side effects 
(including a asking for a repaint of the eel I, which will then triggers another 
repai nt goi ng on forever) . 

The solution would be to change the field, rather than property, but how can we 
accomplish this? I n the past, considering it is a private field, we'd have to use 
some low-level hacks (accessing to a specific memory location), while now we 



83 An interposer classisaclass with thesamenameof theclass it inheritsfrom. By adding 
its unit after the unit of its base class in a uses statement, the program wi 1 1 use the modi- 
f i ed versi on of the cl ass rather than the ori gi nal . I nterposer cl asses are not a terr i bl y neat 
technique, rather a hack. But they can be very handy, indeed! Historically, the name of 
the technique was given in the first article that described it, which appeared manyyears 
ago in 'The Delphi Magazine". 
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can use the extended RTTI to access the private field). Still a low level tech- 
niques, but neater and more flexible in case of future internal changes in the 
class structure. 

Here is the complete code of thePai nt method, which stores thecurrent value 
of the field (directly using itsTVa I ue) and restores it at the end: 

uses 

Rtt i ; 

procedure TDBGrid. Paint; 
va r 

o I d E d i torMode: TVa I ue ; 
context: TRtt i COntext ; 
edi torModeFi eld: TRtt i Fi el d; 
begi n 

e d i t o r Mod e F i e I d := context. GetType(TDbGri d). 
GetFi el d( ' FEdi t or Mode' ) ; 

if Assigned ( edi tor Mo d e F i el d ) then 
begi n 

ol dEdi t or Mode := ed i t o r Mod e F i e I d . Ge t Va I u e ( s e I f ) ; 
edi torModeFi el d. SetVal u e ( s e I f, TVal ue. F r o m( F a I s e ) ) ; 
end; 

// now psi nt 
i nher i ted; 

if Assigned ( edi tor Mo d e F i el d ) then 

edi torModeFi el d. SetVal uefsel f, ol dEdi torMode) ; 

end; 

At the core the method calls the base class version of the method, as managing 
the actual painting of the grid would be daunting (that is, doi ng a copy and 
paste of hundreds of I i nes of source code). The effect of this fix is to get back 
the white area around thein-pl ace editor, shown here, as was standard in past 
versions of Delphi: 
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Midas DLL Now With Source 

A significant change "behind the scenes" in Delphi 
2010 is the availability of the source code of midas.dll. 
This library, which iseither deployed along with your 
application or compiled into the M idaslib unit and 
bound to your executable, is the engine behind the 
ClientDataSet component. I n fact, even if there is the 
full Delphi source code of this component, its actual 
data processing code is inside the DLL, that the com- 
ponent invokes frequently. 

1 1 happened over the last few years that developers 
spotted a couple of bugs in the DLL, which were very 
hard to fi nd and fix given the source code was not 
available. Following complaints by the Delphi com- 
munity, Embarcadero has finally decided to release 
the source code to the public, along with theVCL 
source code 84 . 

I n my i nstal I ati on , the I i brary source code i s i n : 

C:\Program F i I e s \ E mb arcadero\ 
RAD Studi o\7. O\source\db\mi das 

The drawback, though, is that this library is not writ- 
ten in Delphi, but it is a C++ library. If you look at the 
code, you'l I easi I y real i ze that it i s far from easy to 
navigate and study it. Once opened in C++Builder, the 
proj ect structure I ooks I i ke the one of the enti re si de 
of this page. 

The main header files aret a I chemy. h and 
a I chemy. h , which define the data set classes. The 
class structure is very si mple, but the code is far from 
trivial and is almost 15 MB. Other header files and 
core implementations apparently come straight out of 
the Borland Database Engine, with references to the 
I DAP I xx . DLL, headers likebdetypes. h, and the like. 
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84 J ust one example of the improved community relations with Embarcadero. 
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BDE in- memory tables were probably a precursor of theClientDataSet com- 
ponent, so this should be no surprise. 

I didn't do much explorationoftheMidas.dll source code, butl took a little 
ti me to configure the bui Id envi ronment and compi le it: 

/ : : : i — ™ — n 

Information for midas.cbproj 
Program 

Source compiled: 408060 lines 

Code size: 405504 bytes 

Data size: 86016 bytes 

Initial stack size: 0 bytes 

File size: 488960 bytes 

Status 

midas.cbproj Successfully Compiled. 

| OK | | Help | 



As you can see, the library has over 400,000 lines of source code, and although 
the resulting DLL is slightly bigger than the one that ships with Delphi 2010, it 
seems to behave i n the same way. 

Overall, the fact that this source code is available is very interesting, even if 
veryfew Delphi developers would probably work on it directly. What is relevant 
is that some Delphi and C++ experts would have a chance to debug the library 
and make the component faster. For any Delphi users, having the source code 
of a core component provides a big guarantee i n case a critical bug arises, as 
you don't have to wait for Embarcadero to fix it. I n practice this already has 
happened with previous informal fixes (mostly done by And reas Hausladen 85 ) 
now embedded in the current version of the library. 

From a theoretical perspective, it would be much better to have a new Client- 
DataSet component rewritten at a higher level in Delphi and based on the 
internal memory manager, but given this would take quite some effort and it 
could easi ly cause i ncompatibi I ities with existi ng code, the current option to 
make available the M idas DLL source code written in C++ is a good solution. 



85 Again, Andreas blog isat http://andy.jgknet.de. 
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ADO 2.8 Support 

Another change that's very specific to a given set of data access components is 

the upgrade to the latest version of the ADO library, to support version 2.8. As 

you can see in theADOl nt unit, the library versions are declared as: 

ADODBMaj orVersi on = 2; 
ADODB Mi norVersi on = 8; 

There are many other changes in the unit, with the declaration of newer 
internal interfaces and some new constants. There is no significant change in 
the way these interfaces are called by the ADODataSet component, but you'll be 
abl e to more easi I y cal I i nto the newer i nterf aces from you r code. 

There is actually a change in theADODataSet code, a relevant revision (or bug 
fix, if you want to call it that way) of the Par seSQL of theT P a r a me t e r s used to 
extract parameters from an SQL statement. 



dbExpress in Delphi 2010 

In Delphi 2010 there are limited changes to the dbExpress core architecture, 
with most updates tied to specific drivers. This is due to the support for new 
databases (particularly Fi rebi rd, the open source spi n-off of I nterbase), new 
versions of exi sti ng databases, and changes i n the way programs access the 
database (like in case of Microsoft SQL Server). The following sections have 
more details. 

The Firebird Driver 

Firebird is an open source database, developed by the Firebird Foundation, 
that originates from the version of I nterbase that Borland released (even if only 
temporari ly) as open source. Given the relationshi p with I nterbase (the data- 
base distributed with Delphi si nee the early days of the product) and the fact 
that deployment of Firebird isfree, it should come to no surprise that this data- 
base server is quite popular among Delphi developers. I n the early days, the 
two database were highly compati ble, and developers often used drivers and 
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components for I nterbase to connect to Fi rebi rd, but over the years differences 
and incompatibilities started to emerge. 

Despite this tight relationship, both Borland and the Firebird Foundation 
offered limited help in using the two together, because of previous discussions 
and misunderstandings among specific people on the different sides. It was 
only after the acquisition by Embarcadero Technologies that tensions cooled 
off, and the company started planni ng ful I support for both I nterbase and Fi re- 
bird in its database management line of tool sand in its development tools. 

For the first time si nee the Firebird project was started, Delphi 2010 has official 
and specific support for the database, in the form of a dbExpress driver. This is 
not I ike using the I nterbase with different parameters, but it is, to all effects.a 
specific driver supporting the still popular Firebird 15 and the newer Firebird 
2.11 The new driver has a specific DLL, relies on the Firebird client library 
(fbclient.dll) rather than the I nterbase one (gds32.dll), although its entry point 
(getSQLDriverl NTERBASE) is shared. 

This is an example of the configuration of a SQLConnection component with 

the Fi rebi rd driver and one of the default databases: 

object SQLConnect i onl: TSQLConnect i on 
Connect i onName = ' F BCONNECTI ON' 
D r i v e r N a me = 'Firebird' 
Get Dr i ver Func = ' get SQLDr i v er I NTERBASE' 
Li braryName = ' dbxf b. dl I ' 
Para ms. Strings = ( 
' dr i ver name=Fi rebi r d' 

' data base =localhost:C: / Program Files/Firebird/ 
Fi rebi rd2. 1/ exampl es/ empbui I d/ empi oyee. f db' 
■ ■■) 

VendorLi b = ' fbel i ent. dl I ' 
end 

The unit you have to include in the project to manage the specific parameters is 
DBXFirebird. This unit is generally automatically included in forms and data 
modules with an SQLConnection component referring to the Firebird connec- 
tion. I n case you want to perform operations on metadata, the units to i nd ude 
start with the DBXFi rebi rdMetaData unit. 

I haven't done extensive testing with using this driver against Firebird, but I've 
made a few experi ments and it seems quite sol id so far. The DbxMuIti 2010 
example already mentioned earlier for thethemed DBG rid issues is in fact a 
Firebird application with the configuration listed above. I didn't have to make 
any other changes to convert it from I nterbase to Firebird. 
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Updated dbExpress Drivers: I nterbase, 
MySQL, Oracle 

As i n most new versions of Delphi , some of the drivers have been tested and 
updated to work with the latest version of the respective database server: 

• The I nterbase driver has been updated to I nterbase 2009, i ncl udi ng its 
To-Go version (the DLL-based version) 

• TheMySQL driver has been updated to MySQL 5.1 (notice that the 
MySQL client library, libmysql.dll, must match the server version or 
you'll see an exception) 

• The Oracle driver has been updated to Oracle Ug. 

The SQL Server Driver 

The M icrosoft SQL Server driver has been updated, specifically to support M S 

SQL Server 2008, but thisalso implies an architectural change. Whileinthe 

pastthedriver relied on theOLDDB driver (installed along with theMS Data 

Access Components, or MSDAC), the new driver uses the native client. The 

"Microsoft SQL Server 2008 Native Client" can be freely downloaded from the 

M icrosoft web site as part of the "M icrosoft SQL Server 2008 Feature Pack, 

August 2008" or individually in the same page that hosts the Feature pack (just 

scroll down to about half of the page). TheURL 86 is: 

h 1 1 p : / / www. mi crosoft. com/downl oads/detai I s. aspx? 
Fami I yl d=C6C3E9EF- BA29- 4A43- 8D69-A2BED18FE73C 

The architectural change in thedbExpress driver was required because theOLE 
DB support for SQL Server is frozen at SQL Server 2000 i n terms of features, 
whilethe "native client" fully supports version 2005, version 2008, and future 
ones. This includes, for example, support for new data types such asd a t e , 
t i me , d a t a t i me 2 , d a t e t i me of f s e t , and the like. 

In addition to the latest driver, with support for the SQL Server 2008 client lib- 
rary (sqlncli 10.dll), there is a separate backward compatible dbExpress driver 
for SQL Server 2005. The key elements of the two configurations (extracted 
fromthedefaultdbxdrivers.ini file) are listed below: 



86 If you have to type it, you can also use the shorter version http://bit.ly/50uiEP 
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[MSSQL] // Native Client for MS SQL Server 2008 
Li braryName=dbxmss. dl I 
Vendor Li b =s q I ncl i 10. dl I 

[ MSSQL9 ] / / SQL Native Client 2005 
Li braryName=dbxmss9. dl I 
VendorLi b=sql ncl i . dl I 

Notice that the new dbExpress driver for MS SQL also includes support for 
Multiple Active Results Sets (also known by the MARS acronym). 



DataSnap Updates 

We have seen that dbExpress has seen enhancements in several drivers, but 
nothing has changed in terms of its architecture, the components you use, or 
their core features. After its debut in Delphi 2007, the dbExpress IV architec- 
ture is becomi ng quite stable. 

This is not the case with DataSnap, Del phi's three-tier architecture, which has 
been extensively modified in Delphi 2009 and sees the completion of that pro- 
ject in Delphi 2010. 

Overview of DataSnap in Delphi 2009 

Originally based on a COM architecture, in Delphi 2009 the DataSnap frame- 
work was rewritten in terms of connectivity (now based on native sockets) and 
overall architecture, removing all dependencies from COM . 

On the server side, in Delphi 2009 you could use three components 87 : 

• DSServer, the mai n server configuration component, which is needed to 
wire all the other DataSnap components together. 

• DSServerClass, a component needed for each cl ass you want to expose. 
This component i s not the cl ass you make avai I abl e, but acts as a cl ass fact- 
ory to create obj ects of the cl ass you want to cal I from a remote client. I n 
other words, the DSServerCI ass component wi 1 1 refer to the cl ass that has 
the public interface. 



87 This description isextracted from my "Delphi 2009 Handbook", which has more details 
and specific examples I 'm not going to repeat here. 
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• DSTCPServerTransport, a component that defines the transport pro- 
tocol to be used (this is the only protocol directly available in Delphi 2009) 
and its configuration, such as which TCP/ 1 P port to use. 

On the client side, you still usetheClientDataSet component for caching the 
remote data, but the way you connect to the server has changed from the past. 
The components involved are: 

• SQL Connecti on, generally used for dbExpress connections, has a Data- 
Snap driver you can configure with the proper TCP/ 1 P port. 

• DSProviderConnection, used to refer to the server class, with the 
ServerCI assName property. This is the actual class you want to work with, 
not the DSServerClass object. This DSProviderConnection can be referenced 
by the Re mot eSer ver property of the CI ientDataSet. 

• Sql Server Method, used to i nvoke a server side method directly (as if it 
was a stored procedure i n a database) . 



Overview of DataSnap in Delphi 2010 

Given this new foundation, in Delphi 2010 there have been several extensions. 
The most significant is probably the addition of a new connectivity option, 
HTTP, which can be used i nstead of sockets or alongside with them. 

Along with HTTP support, which still relies on dbExpress for client connectiv- 
ity, DataSnap in Delphi 2010 also has REST support, which lets you create 
clients in any language which can send an HTTP request and process the res- 
ultingj SON data structure. We'll explore REST support in the next chapter. 

Beside HTTP and REST connectivity, new features of DataSnap include the fil- 
teri ng system, support for callbacks, and passing objects using the J SON 
marshali ng layer. There are also a couple of very nice wizards to start the devel- 
opment of a new standalone DataSnap application or one hooked to an HTTP 
server (based on the classic Delphi WebBroker framework). Now that you 
should have an idea of the key elements, I can start getti ng to the actual detai Is, 
starting with HTTP support. 
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DataSnap over HTTP 

As a fi rst example of DataSnap based on the new HTTP connectivity, I 've exten- 
ded the First3Tier2009 demo that I built for the Delphi 2009 Handbook 88 . In 
the server I replaced the TCP/ 1 P transport component with theDSHTTPSer- 
vice component, configured as: 

object DSHTTPServi eel: TDS HTT P S e r v i c e 

RESTContext = 'rest' 

Server = DSServerl 

Filters = <> 

Htt pPort = 8 0 9 0 

Active = False 
end 

The A c t i v e property of the component is set to True when the server mai n 
form is created. That's the only change I had to make. 

Notice I could have kept the TCP/ IP connection along side the HTTP one: it 
might makesenseto use the direct TCP/ 1 P connection for internal clients run- 
ning within the company (inside the firewall and in a protected Intranet or 
under a VPN), and open uptheHTTP port for external connections coming 
from the I nternet. I 'II cover some more scenarios and configuration options 
later in this chapter. 

For now, having migrated the server let me focus on the client. I n this case, 

what we have to do is update the SQLConnection component configuration, 

which becomes the foil owing: 

object SQLConnect i onl: TS QL Co n n ec t i o n 
DriverName = 'Datasnap' 
LoginPrompt = False 
Para ms. Strings = ( 
' Port =8090' 

' Communi cationProtocol=http' 
' Dr i ver Uni t =DBXDat aSnap ' ) 

end 

That's it. All I had to do was change the configuration of the DataSnap driver, 
typi ng http i nstead of tcp/ i p and enter the correct port number, matchi ng the 
one I 'd configured on the server. 



88 Full source code of the example is avai lable in the codesection of my web site at: 
http://www.marcocantu.com/code/dh2009/First3Tier2009_Server.htm and 
http://www.marcocantu.com/code/dh2009/First3Tier2009_Client.htm. 
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A DataSnap HTTP Server with the Wizard 

For that first demo I've taken an existing DataSnap application and moved it 
from a TCP/ 1 P connection to an HTTP connection. It is even easier to create a 
new application with the DataSnap Wizard and ask for either or both con- 
nectivity options. If you select the DataSnap Server in the DataSnap page of the 
New Item dialog box (or Object Repository) you'll get the foil owing options: 

' i to n 

New Da:aSnap Server [ - - > 

You may select from one of the following applications types 

® vCL Forms Application 
C_ j Console Application 
© Service Application 

You may select one or more communication protocols 

S TCP/IP 
□ HTTP 

I I Authentication 

H Add Server Methods Class 

Ancestor: |TDSServerModule -| 
[7] Include sample methods 

OK Cancel Help 



You can pick three different application architectures, one or both communica- 
tion protocols (optionally asking for HTTP Authentication) and add a ready to 
use server method class based on a DataSnap Server Module, a plain Data 
Module, or a plain T P e r si stent ancestor. Depending on the options you pick, 
you can have a variety of structures for your DataSnap server. I n each case, the 
wizard will generate a data module with the core DataSnap server components, 
pi us the modules you ask for. 

Lets suppose I pick a Console Application, HTTP with Authentication, and a 
server method class based onaTPersi stent ancestor with the sample meth- 
ods. The wizard will generate two units and a project file, available in the 
DSnapHttpConsole project with the original unit names suggested by the Data- 
Snap Server Wizard. 
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The main project file for the console application, has a single call (protected by 
an exception handler) toaRunDSServer function: 
try 

Run DS Server; 
except 

on E: Exception do 

Wri tel n( E. CI assName, ' ; ', E. Message); 

end 

The ServerContainerUnitlunit is a data module hosting the DSServer, 

DSServerClass, and DSHTTPService components already used in the previous 

example, plus the DSHTTPServiceAuthenticationManager component I asked 

for in the Wizard. 

object ServerContai nerl: TServerContai nerl 
obj ect DSServer 1: TDSServer 
Autostart = True 
Hi d e DS A d mi n = False 
end 

object DSHTTPServi eel: TDS HTT P S e r v i c e 

Server = DSServerl 

DSHostname = ' / oca I host ' 

Authenti cation Ma nager = 

DSHTTPServi ceAuthenti cati onManagerl 

Ht t pPor t = 8 0 9 0 
end 

obj ect DSHTTPServi ceAuthenti cati onManagerl: 
TDSHTTPServi ceAuthenti cati on Ma nager 

end 

object DS Se r ver CI as s 1 : TDS S e r ve r CI a s s 

OnGetCI ass = DSServerCI asslGetCI ass 

Server = DSServerl 

Li f eCyc I e = 'Session' 
end 
end 

Beside the port and host name configuration, notice theOnGet CI ass event 
handler of the DSServerClass isdefined there and implemented by the Wizard. 

I n the server class configuration above, I let the DSServerClass component use 
the default value of the Li f eCycl e property. Session, but this is totally ignored 
and behaves I ike a TCP/ IP server when the Invocation life cycle is used. This 
means a new server class object is created for each client request, which should 
not be surpri si ng gi ven the useofHTTP.TheHTTP con necti on i s a state! ess 
connection, which means a new connection to the server is established for each 
client request (with some very limited exceptions). 

I n case of a console appl ication, the ServerContai nerU nitl unit also i implements 
theRun DSSer ver global function, which creates the data module and starts the 
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DSServer. The code waits until the Esc key is pressed to terminate the console 
application: 
va r 

LModule: TServerContai nerl; 
LI nputRecord: TlnputRecord; 
begi n 

LModule := TServerContai nerl. Create( ni I ) ; 
try 

LModul e. DSServerl. Start ; 
try 

while True do 
begi n 

. . . check for Esc key 

The ServerMethodsUnitlunit has the target class (automatically connected to 
the DSServerClass component of the main unit, as mentioned earlier) with the 
sample method: 
type 

{ $METH0DI NF 0 ON} 
TServerMethodsl = classfTPersi stent) 
public 

function EchoStri ng(Val ue: string): string; 
end; 

{ $METH0DI NFO OFF} 

This is al I the code generated for the server. We can try to compi le and run it as 
it is, but how do we test it without creating a client application? Turns out we 
can use the Data Explorer pane of the Del phi I DE. 



Testing the Connection in Data Explorer 

It is interesting to notice that in the Data Explorer window of the Del phi 2010 
IDE you can configure and test the client connection quite easily. It is actually 
easier to test the connection in this pane than setting up an SQLConnection 
component manually. 



To try this out, si mply run the 
server ( possi bly as a stand 
alone application using the 
Run Without Debuggi ng com- 
mand), move to the Data 
Explorer, pick the DataSnap 
driver, and add a new connec- 
tion. Now open the 



Modify Connection KK*aM< 




Data source; 

"dbBqjresa (dbBqwess Provider}" 






DatsSnap Server address 
Protocol: hap ▼ 






Host: locales 






Port BOM 






P»rh 
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Data Explorer 



connection configuration and enter the settings for your server (including host 
and port), as shown here. Test the connection to see if it is OK and the server is 
running. 

Now you can check the connection 
features in the Data Explorer pane. 
The DataSnap connection will have no 
tabl es, but wi 1 1 have a set of proced- 
ures correspondi ng to the methods 
exposed by the server, which include 
the admi nistrati ve methods and the 
specific ones provided by your server 
class (or classes). With this example 
you'll seetheliston the side of this 
page. 

Now you can even select the given 
server method, open its parameters, 
set their Va I ue property (in this case 
the parameter itself is cal led Val ue, 
causing some confusion), and even 
execute it from the I DE by using the 
right mouse button in the pane with 
the stored procedure parameters, dis- 
played below. Here the result data set, 

which has a single element with the return value (the parameter echoed from 
the server back to the cl i ent) , i s di spl ayed . 
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HTTP Authentication 

I n this application I asked the Wizard to add support for HTTP authentication, 
but haven't actually used it so far. What you have to do is handlethe 
HTTPAut hent i cate event of theDSHTTPServiceAuthenticationManager com- 
ponent. I n this event handler you receive the user name and the password, but 
also more i nformation about the i ncomi ng request (so you could have a differ- 
ent authentication strategy dependi ng on the request) . I n this very si mple case 
I've used the simplest possible implementation, a fixed user name and pass- 
word (no, it is not my real password!): 

procedure TSer ve r Con t a i ne r 1 , 

DSHTTPSer vi ceAut hent i cat i onManager lHTTPAut hent i c a t e ( 
Sender : TObj ect ; 

const Protocol, Context, User, Password: string; 
var valid: Boolean); 
begi n 

valid : = (User = 'marco') and (password = '123'); 
end; 

Notice that the authentication request comes in for every single HTTP request, 
as the protocol is i nherently stateless. Now if you compi le and run the server 
with authentication support and connect from the Data Explorer DataSnap 
driver, you'll see an error like: 




All you have to do it enter the user name and password in the Authentication 
section of the connection configuration (displayed earlier in the section 'Test- 
ing the Connection in Data Explorer"). 

Building a Client Application the RAD Way 

There isn't a wizard to build DataSnap client applications, but once you have 
configured the connection in Data Explorer, you can take advantage of its drag- 
and-drop capabilities. 

For example, if you drag the connection defined earlier and called "FIRST" over 
the form, you'll get the foil owing: 
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obj ect FIRST: TSQLConnect i on 
Connect i onName = ' Fl RST' 
Dr i ver Name = ' DATASNAP' 
Logi nPrompt = False 
Para ms. Strings = ( 

' dr i ver na me =DAT ASNAP' 

' port =8090' 

' communi cationprotocol=http' 

'hostname=localhost' 

' DSAu t h e n t i c a t i o n Us e r =ma rco' 

' DSAu t hen t i c at i on Pass wo r d =123' ) 

end 

The inter esti ng thi ng is that the config- 
uration of the communication protocol 
is easier in the connection editor than 
it is in the Obj ect Inspector. In the 
former, in fact, you have the various 
options (http ortcp/ip) in a combo 
box, whi le i n the Object I nspector you 
have to type i n the val ue, as you can see 
here on the right. 

Notice also that the properties used for 
the user name and the password: these are not the U s e r n a me and Password 
properties, but the DSAut hUser property (stored i n the P a r a ms as DSAu- 
thenti cation User) andtheDSAUt hPassword property (stored as 
DSAuthenticationPassword). 

Once you have the SQLConnection component in place, we can think of turning 
it on. This won't work at design time, nor if you call the Open method of the 
connection at run time. In this second case you'll get the error: 



Debugger Exception Notification 





ProjectConsoleClient.exe raised exception dass TDBXError with message 'Protocol http can be used after an 
adequate instance ofTDBX Communi cation Layer is registered withTDBXCommunicatjonLayerFactory.', 

Break | Continue j Help 

1 1 Ignore this exception type 









The error indicates that the communication protocol has not been registered, 
and you can do this by adding a reference to the DSHTTPLayer unit: 

uses 

DSHTTPLayer ; 



r a 


Object Inspector 




| FIRST TSQLConnection 




| Properties | Events 1 




Connected 


□ False 




ConnectionName 


FIRST 




Driver 


DAT AS MAP 






BufferKBSize 


32 


» 


Corn muni cation Protocol 


http 






ConnectTimeout 








DSAuth Password 


123 






DSAuthUser 


ma rco 






HostName 


localhost 






PassWord 








Port 


8090 
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Now we can do another drag-and-drop operation for calling the only method of 
the server. I f you open the I i st of procedures and drag the one you want to cal I , 
the forms will have an SQLDataSet component configured as a stored proced- 
ure: 

object TS e r ve r Me t ho ds 1_ Ec ho S t r i ng : TSQLDat aSet 

CommandText = ' TSer ver Met hods 1 . Ec hoSt r i ng ' 

C o mma ndType = ctStoredProc 

SQLConnect i on = Fl RST 
end 

I f you try to cal I i t, however, i t wi 1 1 f ai I , as the remote server won 't recogn i ze a 
request referring to a stored procedure. What you have to do is manually 
change theCo mma ndType toe t Ser ver Met ho d . When you do so, however, the 
value of theCommandText property (which iscorrect) will be reset. So you 
shoul d copy the C o mma n d T e x t , change the C o mma n d T y p e , and then paste the 
CommandText back 89 . 

Overall, you'll get the component configured as follows, including its input and 

output parameters: 

object TS e r ve r Me t ho ds 1_ Ec ho S t r i ng : TSQLDat aSet 
CommandText = ' TSer ve r Met ho ds 1 . Ec ho St r i ng ' 
Co mma ndType = ctServer Method 
DbxCommandType = 'DataSnap.ServerMethod' 
MaxBI obSi ze = - 1 
P a r a ms = < 
item 

DataType = ftWi deStri ng 

Precision = 

Na me = 'Value' 

P a r a mT y p e = p 1 1 n p u t 
end 
item 

DataType = ftWideString 
Precision = 2000 
Name = ' Ret ur nPar amet er ' 
ParamType = ptResult 
Size = 2000 
e nd > 

SQLConnect ion = FIRST 
end 

Now al I you have to write is the code for setti ng the i nput parameter, execute 
the server method, and retrieve the result: 



89 The fact that the text of the command i s I ost as you change the command types makes 
sense when changi ng from a table to a query, but when switchi ng between two named 
objects (like in this case) it could have been preserved. I won't say this is a bug, though: 
better fix the drag-and-drop behavior! 
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procedure TConsol eCl i ent For m. bt nCal I EchoCI i ck( Sender : TObject); 
begi n 

TServerMer.hodsl_EchoSr.ri ng. P a r a mB y N a me ( ' Value') . 
AsString := 'Hello ' + TimeToStr (Now); 

TserverMer.hodsl_EchoSr.ri ng. ExecSQL; 

S ho wMes sage ( TServer Met hodsl_EchoSt r i ng. 
ParamByNamef ' Ret urn Par a met er ' ) . AsStr i ng); 

end; 

As an alternative, you can avoid draggi ng the procedure and addi ng the data set 
altogether, by usi ng the "Generate DataSnap cl ient classes" command of the 
SQLConnection component to generate the client proxy classes for the server. I 
did that and saved the new unit as CI ientProxy. Now you can refer to the unit 
and replace the component and the call above with the creation of an instance 
of the proxy and its use: 

uses 

CI i entProxy; 

procedure TConsol eCl i entForm. btnProxyCI i ck( Sender: TObject); 
begi n 

with TSer ver Met hods 1CI i ent . Cr eat e( Fl RST. DBXConnec t i on) do 
try 

ShowMessage ( Ec ho St r i ng ( ' Hel I o ' + TimeToStr (Now))); 
finally 

Free; 
end; 
end; 

This last part of the appl ication was not exactly based on a visual development 
style, but it was certainly worth mentioning it as a relevant alternative for call- 
i ng server methods. 



DataSnap WebBroker I ntegration 



Building an application to run on the server (whether a standalone VCL pro- 
gram, a service, or a console application) is only one of the options for 
deploying DataSnap servers in Delphi 2010 or, to be more precise, to offer 
HTTP connectivity to DataSnap servers. 

The alternative option is to create and deploy Web server extensions, based on 
Delphi's classic WebBroker architecture. 



Marco Cantu, Delphi 2010 Handbook 



222 - Chapter 7: Database Access and DataSnap 

Overview of the WebBroker Architecture 

This overview is meant as a short introduction of a technology that 
has existed since Delphi 3 9 °, for those who never used it or used it only 
occasionally. If you already used WebBroker you can certainly skip it. 

The WebBroker technology, availablein Delphi si nee the early days of the 
product, is a framework to let you create Web server extensions that can be 
deployed as CGI applications, ISAPI libraries, and (even if unofficially) Apache 
modules. There is a fourth option, which is the use of a debug tool, called Web 
App Debugger as a replacement for a web server whi le developi ng and debug- 
gingthe application. 

A WebBroker application is built around a WebModule designer, which has an 
object holding the web request received from the client and the web response, 
plus a collection of actions tied to the i ncomi ng URLs. ThisT We b Mo d u I e 
derives from TCu s t o mWebDi s pa t c her , which provides support for all the 
i nput and output of your programs and defi nes the R e q u e s t and Response 
properties. 

These properti es are defi ned usi ng a base abstract cl ass (T We b R e q u e s t and 
TWebResponse), but an application initializes them using a specific object 
(suchastheTI SAPI Request andTI SAPI Response subclasses for an ISAPI 
I i brary) . These cl asses make avai I abl e al I the i nformati on passed to the server, 
so you have a si ngle approach to accessi ng al I the i nformati on. 

The key advantage of this approach is that the code written with WebBroker is 
independent of the type of application (CGI, ISAPI, Apache module); you'll be 
abl e to move from one to the other, modi fyi ng the proj ect f i I e or swi tchi ng to 
another one, but you won't need to modify the code written in a WebModule. 

To write the application code, you can use the Actions editor in the WebModule 
to define a series of actions (stored in the Act i ons array property) depending 
on the path name of the request. This path name is the portion of request URL 
that comes after the program name and before the parameters. 

By providing different actions, your application can easily respond to requests 
with different path names, and you can assign a different producer component 
or call a different On Ac t i o n event handler for each and every possible path 



90 As a historical reference you can see http://edn.embarcadero.com/ article/ 10 134 
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name. IntheOnAct i on event handler, you write the code to specify the 

response to a given request, as in the following code snippet, which returns 

some plain HTML: 

procedure TWebModul el. WebModul elWebActi onl temlActi on ( 
Sender: TObject; Request: TWebRequest; 
Response: TWebResponse; var Handled: Boolean); 
begi n 

Response. Content := 

' <ht ml xheadxt i 1 1 e>Hel I o Page</ 1 1 1 1 ex/ headxbody>' + 
' <hl>Hel I o</ hl>' + 

' <hr xpxi >Page generated by Mar co</ i ></ p>' + 
' <l body ></ ht ml >' ; 

end; 

As debugging web applications is often difficult, Delphi offers a specific Web 
App Debugger program. This program, which is activated by the corresponding 
item on the Tools menu, is a web server that waits for requests on a port you 
can set up (8081 by default). When a request arrives, the program can forward 
it to a stand-alone executable using a socket connection. 

Using this tool you can run the web server application from within the Del phi 
I DE, set all the breakpoints you need, and then debug the program as you 
would a plain executable file. 

The Web App Debugger also does a good job of logging all the received requests 
and the responses returned to the browser, letting you inspect the data flow at 
the HTTP protocol level. 



The DataSnap WebBroker Wizard 

Creating DataSnap applications based on the WebBroker architecture is reas- 
onably simple thanks to another new Wizard added to the Del phi 2010 IDE, the 
DataSnap WebBroker Application wizard. 

Differently from the DataSnap Application Wizard, this one won't let you pick a 
TCP/ 1 P connection and offers you the appl ication types supported by 
WebBroker as options, rather than the development of full-blown, console, or 
service applications. You can see the Wizard form in the next page. 
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New DaiaSnap WebBroker Application 



You may select from one of the following types of World 
Wide Web server applications. 

■« ISAPI/NSAPI Dynamic Link Library 
■ CGI Stand-alone executable 
O Web App Debugger executable 

Class Name: 



You may choose from the following DataSnap options 

Support HTTP Authentication 
[7| Add Server Methods Class 



Ancestor: TDataModule 



F71 Include sample methods 



Help 



To build an example I 've picked the Web App Debugger executable option and 
given a name to its class 91 . The Wizard generates a unit with the target Server 
Methods class (again a DataSnap Module, a Data Module or aTPer s i stent 
descendant), plusa Web Module hosting the DSServer and DSServerClass 
components. 

The web module has one extra new component, DSHTTPWebDispatcher, 

which provides the conduit between WebBroker and DataSnap, by hooking to 

the web dispatch mechanism and intercepting the incoming requests that start 

with a given path name. The component has these default settings: 

object DS HTTP We b Di s pa t c he r 1 : TDSHTTPWebDi s pat c her 
RESTContext = 'rest' 
Server = DSServer 1 
DSHostname = ' / oca I host ' 
DSPort = 211 

WebDi spatch. MethodType = mtAny 
We b Di s p a t c h . P a t h I nf o = 'datasnap*' 
end 

The key property here is the P a t h I n f o i ntercepted by this dispatcher, anythi ng 
starting with datasnap. The REST information is relevant, but I 'II focus on that 
topic in the next chapter. Finally, the DataSnap host and port configurations 
are used only in case of a gateway, covered in a later section. 



91 This class name is a registration name (nothing to do with a Delphi class) provided by 
the program and used along with the application name to refer to the module in a URL. 
This name is saved in a registration line inside the initialization section main form unit, 
in a call to the constructor of theT We b App So c kObj ectFactory class. 
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Using this Wizard I've built the DSnapWebAppDebug project, which registers 
the'dsnaplhttp' class name (we'll seeitsURL as we move to the client- side 
project) . The project has an empty and useless mai n form, I i ke any Web App 
Debugger application, a web module, and a data module. 

The web module has a DSHTTPWebDispatcher component with the default 

settings I 'vejust listed, a DSServer component and a DSServerClass, connected 

to the sample target data module. The web module also has a default action 

(that is an action matching any path not configured in a dispatcher) defined as: 

object WebModul e2: T We b Mo d u I e 2 
Actions = < 
item 

Default = True 

Name = ' Def aul t Handl er ' 

Pat hi nf o = 7 ' 

OnAction = We b Mod u I e 2 Def a u I t Ha nd I e r Ac t i o n 
e n d > 

The code of this event handler is quite trivial: 

procedure TWebModul e2. WebModul e 2 De f aul t Handl erAct i on ( 

Sender: TObject; Request: TWebRequest; 

Response: TWebResponse; var Handled: Boolean); 
begi n 

Res po ns e . Co n t e n t := ' <ht ml xheadi ng/ ><body>' + 
'DataSnap Ser ver </ bodyx/ ht ml >' ; 

end; 

Rather than changing this HTM L 92 in code, you can return the content of a local 
HTML file, in mycode'main.html', to be used asastandard response. Thisway 
you can customize the default page returned by the server without having to 
recompilethe application. This isthe updated On Ac t i on event handler for the 
default action: 
var 

strRead: TStreamReader; 
begi n 

strRead : = TStreamReader. Create! ' mai n. bt ml ' )\ 
Res po ns e . Co n t e n t := strRead. ReadToEnd; 
st r Read. Free; 

You can add actions to this web module, likeany WebBroker application. 

The third unit of the project is a data module, which has a Firebird dbExpress 
connection (but you can use any other supported target database). The three 



92 Oddly enough the code generated by the Wizard uses a heading tag rather than HTML's 
head tag. Not a big deal, as you are supposed to replace it with your own HTM L anyway. 
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components in this data module are (a connection, a data set, and a provider), 

listed herewith only their key properties: 

object FBCONNECTI ON: TSQLConnecti on 
Connect i onName = ' F BCONNE CTI ON' 
D r i v e r N a me = 'Firebird' 
end 

object CUSTOMER: TSQLDataSet 
CommandText = 'CUSTOMER' 
C o mma ndType = ctTable 
SQLConnect i on = FBCONNECTI ON 
end 

object Da t a Se t P r o v i de r 1 : TDataSetProvi der 

DataSet = CUSTOMER 
end 

The program has also two methods, thesampleEc h oSt r i ng (which inthiscase 
doubles the string passed as parameter) and a Get Da t a Set method returning a 
data set: 



publ i c 

function EchoStri ng(Val ue: string) 
fundi on Get Dat aSet : T Da t aset ; 



s t r i ng ; 



Once you compilethis application, you not only have to run it but also activate 
the Web App Debugger (from theTools menu of the Del phi IDE), which acts as 
the web server whi ch wi 1 1 red i rect the cal I s to the appl i cati on . 



I Web App Debugger 



0 



Server Help 



Stop 



Port: gos \ 

Default URL: h ttp: /flocalhost: 303 lfierverlnfo .Serverlnfa 



Statistics | |_og 



RequestCount: 0 
Total Response Time: 
Avg Response Time: 
Last Response Time: 
Min Response Time: 
Max Response Time; 

Reset 



Once you open the Web App Debugger you can start its service and it will sug- 
gest theURL of the Serverlnfo application, which will list all programs that 
you've registered for the Web App Debugger. This lets you easily find the URL 
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of the given project. However, if you know how this is defined, it won't be diffi- 
cult to get it manual ly: 

http: / / I ocal host: 8081/ dsnapwebappdebug. dsnaplhttp 

First comes the server and the port, followed by the application name dot the 
registered class name I mentioned earlier. If you type this URL in a browser 
you'll see the static HTML file returned by the program. 

Although you could possibly try to invokespecific features of the server, there 
is very little you can do with the HTTP interface, which remains basically a pro- 
prietary interface. To be able to refer to the server methods from a browser 
you'll need to use the new REST support of DataSnap, covered in the next 
chapter. 

A Client for the Web Server 

Now that we have bui It a DataSnap server deployed as a web server extension, 
we have to change a few things in how a client application refers to it. The SQL- 
Connection component, in fact, won't refer to the server using host name and 
port, but usi ng the server base URL: 

object SQLConnect i onl: TS QL Co n n ec t i o n 
D r i v e r N a me = 'Datasnap' 
Logi nPrompt = False 
Para ms. Strings = ( 

' URL Pat h=ht t p: II I ocal host : 8081/ ' + 

' DSnapWebAppDebug. dsnaplhttp' 
' Communi cationProtocol=http') 

end 

Again, you'll also need to add theDSHTTPLayer unit to the client application. 
ThistimebesidecallingtheEchoSt r i ng method on the server, the client 
application reads the remote data set into a I ocal CI ientDataSet component, 
showi ng the data i n aDBGrid. Nothing new for those who have used DataSnap 
in Delphi 2009, but slightly different from past versions of this technology. 

The key components I 've added to the mai n form of the client appl i cation to 
fetch the data set from the server area SQLConnection, a DSProviderConnec- 
tion referri ng to the server class, and a CI ientDataSet pointing to a specific 
provider: 

object SQLConnect i onl: TSQLConnect i on 
DriverName = ' Da t as nap' 
Para ms. Strings = ( 

' URL Pat h=ht t p: 1 1 1 ocal host : 8081/ ' + 
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' DSnapWebAppDebug. dsnaplht t p' 
' Communi cationProtocol=http') 
end 

object DSProvi derConnecti onl: TDSProvi derConnecti on 

ServerCI assMame = ' TSer ver Met hods 1' 

SQL Co n n ec t i o n = SQLConnect i onl 
end 

object CI i ent DataSet 1: TCI i ent Dat a Set 

Provi derName = ' Dat aSet Pr ovi der 1' 

RemoteServer = DSProvi derConnecti onl 
end 

object DataSourcel: TDataSource 

Dat aSet = CI I ent Dat aSet 1 
end 

obj ect DBGri dl: TDBGri d 

Da t a Sou r c e = DataSourcel 
end 

To fetch the data from the server there is no specific code, but a request to open 
theClientDataSet as the program starts. The client application has some actual 
code used to call the Server Methods, but this is exactly I ike the earlier code. 

Overall, we have deployed our DataSnap server as a Web Server extension, and 
after the development could move to a CGI , I SAPI DLL 93 , or Apache Module 
project. Still, the client is nothing but a Delphi client which uses the DataSnap 
driver of dbExpress, much I ike the earlier HTTP DataSnap servers or the 
TCP/IP based ones. 



Filtering Connections 



One of the most relevant requests developers had for DataSnap was the ability 
to compress and encode the data stream. The former helps with performance, 
while the second makes sniffing the data moved over the wire a little more dif- 
ficult. In Delphi 2010 DataSnap introduces more than this, as it features a 
filtering architecture you can use to hook any filter to the input and output 
streams. Even more, the server publishes information about thefi Iters it used, 
so that the client can decode the stream in a proper way (but can also connect 
to multi pie different servers with the same basic code) . 



93 For an example of deployment of a DataSnap WebBroker application in IIS, you can 
refertothefollowingblogentrybyDelphi R&D memberj imTierney: 
http:// bl ogs.embarcadero.com/ j imtierney/ 2009/ 08/ 20/ 31502 
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Using ZlibCompression 

Let me start by showing you how to use the only filter 94 the ships with Delphi, 
the compression filter. First, I 've built a sample DataSnap WebBroker server, 
using the Web App Debugger support, and built a corresponding client. They 
can be found in the DSnapFi Iter Demo folder. The reason for pi eking the Web 
App Debugger is you can easily monitor the HTTP data. For example, the 
response of the method call passi ng the stri ng 'This is my name' lookslike: 

HTTP/ 1.1 200 200 OK 
Connection: close 
Content-Type: text/html 
Cont ent - Lengt h: 57 

{ " r e s u I t : [ {"rows": [ 0 ] } , {"data": [17, A/ T h i s is my name]}]} 

As a second step, I 've added the Z I i bCompressi on transport f i Iter to the 
server side application (more precisely to the DSHTTPWebDispatcher compon- 
ent of the DataSnap server). J ust edit the Filters collection of this component, 
add an entry, and configure it in the Object I nspector: 



j£ Object Inspector 



TTra n sport FilterCollexrtion [0] TTransportFilterltem 
| Properties | Events 1 



Filterld 
Properties 



ZLibCompression 
fTFilterP roper ties) 



@ Editing DSHTTPWebDispatc... Im^—J 



[0 - -r--i-DZ--:.- ts'i:e:"! 



The DSH TTP WebD i spatcher component wi 1 1 have the f ol I owi ng conf i gurati on : 

object DSHTTPWebDi spatcherl: TD5 HTT P We b Di s p a t c h e r 
RESTContext = 'rest' 
Server = DSServerl 
Filters = < 
item 

Filterld = 'ZLibCompression' 
end> 

WebDi spatch. MethodType = mtAny 
We bDi spatch. Pathl nfo = ' datasnap*' 
end 



94 Rumorssaythatmorefilterswerereadytoship, but Embarcadero's legal department got 
worried about shipping strong encryption software, so they were removed at the very last 
minute. 
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Remember that you can also apply filters to a DSTCPServerTransport compon- 
ent, in the case of a socket- based DataSnap server. Now if you fire up the client 
application, you'll see an error I ike the following: 



r 


Debugger Exception Notification 1. 






Project Projectl.exe raised exception dass TDBXError with message 'Communication filter ZLibCornpression is not 
registered. Filter dass needs to be registered in order to communicate with the server.'. 






Break J I Continue J Help 

1 1 Ignore this exception type 











As the error message indicates, the exception isdue to the fact that the client 
request doesn't recognize the filter, which was not compiled and registered into 
the client application. 

What you need to do is to add the compression filter unit to the client program 
(beside the DataSnap HTTP client support unit every DataSnap client based on 
HTTP must declare): 
uses 

DSHttpLayer, DbxCompressi onFi I ter; 

Now the client program works again, with the compressed stream. The HTTP 
data for the si mple response becomes the following unreadable text: 

HTTP/ 1. 1 200 200 OK 
Connection: close 
Content-Type: text/html 
Cont ent - Lengt h: 61 

x #« V* J - . i ) Q 2 5 ®V * E / / #2 
b k u a • R#K##Cs#u! # m A 
@" [ >#[#[# 

There is actual ly no real compression i n this very short response (the Content- 
Length is about the same), but there is when the amount of data is bigger. Now 
this data looks unreadable, but a si mple Unzip request will reveal the content. 

What we might need is to encode or encrypt the content. H ow do we accom- 
plish this? In more general terms, if ZLibCornpression isthe only available 
DataSnap fi Iter, how do we i implement a custom one? 
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Creating Custom Filters 

To add a custom filter to the DataSnap connection layer, what you have to do is: 

• Create a package featuring a transport filter class that inherits from the 

TTransportFi I t er class 

• Implement the Pr oc es s I n pu t and ProcessOutput virtual methods of this 
class 

• Register the transport filter and install the package with the filter in the 
Delphi IDE. 

The DSnapF i I terDemo fol der contai ns the DSnapF i I terO 1 package with a tri vi al 
MIME encoding filter. Theclass of the filter isdefined as: 
uses 

DBXTransport, I dCoderMI ME; 
type 

T Mi me Filter = class (TTransportFi I ter) 
public 

function Pr oc es s I np ut ( c o ns t Data: TBytes): TBytes; override; 
function Pr oc es s Out pu t ( con s t Data: TBytes): TBytes; override; 
function Id: string; override; 
end; 

Thecodeof these three methods is not particularly complex. Thel d function 

returns a unique identifier for thefilter (passed also to the client in the stream): 

function T M i me F i I ter. I d : string; 
begi n 

Result := ' Cant ool s . Mi meFi 1 t er ' ; 
end; 

The Processl n p u t and ProcessOutput methods process the bytes stream 

usi ng I ndy's T I d Encoder Ml ME andTI d Decoder Ml ME support classes: 

function TMi meFi I ter. Processl nput(const Data: TBytes): TBytes; 
va r 

strEncoded: string; 
begi n 

strEncoded := T I d E n c o de r Ml ME . E nc od e By t es ( Da t a ) ; 
Result : = Byt es Of ( s t r Enc oded) ; 
end; 

function TMi meFi I ter. ProcessOutput(const Data: TBytes): TBytes; 
va r 

strEncoded: string; 
begi n 

strEncoded : = Stri ngOf ( Data) ; 

Result := T I d De c o de r Ml ME . Dec od e By t es ( s t r E n c o de d ) ; 
end; 
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Theunit also performs the registration (and de- registration) of the filter, some- 
thi ng both the server and the d ient must do. 

initialization 

TTransportFi I terFactory. Regi sterFi I t e r ( T Mi me F i I ter); 
finalization 

TTransportFi I terFactory. Unregi sterFi I terfTMi me F i I ter) ; 
Also the package needs the registration 



code to let you see the new transport obiact lnspe * tar S B 

TTransportFiH:erCollect"ion[0] TTransportFilterltem •*> 

filter at design time and pick it from , , 

[Properties | Events 



Filterld IffllBIii.lBiBI hJ 

Properties |{TFilterProperties) 



the I ist of fi Iters i n the Object I nspector » intend 
(displayed here no the right side) while Properfa 
conf i guri ng the F i I ters col I ecti on of the 

DSHTTPWebDispatcher component. The settings of this component now 

become the following (this is the code in the final version of the demo): 

object DS HTTP We b Di s pa t c he r 1 : TDSHTTPWebDi s pat c her 
RESTContext = 'rest' 
Server = DSServerl 
Filters = < 
item 

Filterld = 'Can tools. Mi me Filter' 
end> 

WebDi spatch. MethodType = mtAny 
We b Di s p a t c h . P a t h I nf o = 'datasnap*' 
end 

Notice that you can havemultiplefilter processing the data stream. The client 
will applythem in the reverse sequence of the server. Keep also in mind that in 
this case both the client and the server applications must include the filter unit, 
which in the example is the DSnapFilter64 unit. With this specific filter, the 
HTTP data packet when recei vi ng the response of the server method becomes: 

HTTP/ 1, 1 200 200 OK 
Connection: close 
Content-Type: text/html 
Cont ent - Lengt h: 76 

eyj yZXNlbHQi 01 1 71 nj v d 3 Mi 01 swXXOseyJ kYXRhl j p b MTc s wC9 Ua Gl zl Gl zl G15I G5 
. hbWVdf V19 

A M I M E-encoded data stream provides just a little bit of data garbling, but it 
isn't in any way a secure mechanism. If you areinterested in real encryption fil- 
ters for DataSnap, you can refer to the hash and ci pher fi Iters part of the 
"DataSnap Filters Compendium" that DanieleTeti put together and you can 
fi nd on Google Code at: 
http: / /code, googl e. com/ p/dsfc/ 
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J SON and Object Marshaling 

There is another new feature in Delphi 2010 that makes a huge difference in 
the architecture: the types of parameters for server methods now include 
TJ SONVal ue and descendant types. What is relevant here is not the ability to 
pass individual values (integers, strings), but the fact you can use this approach 
to pass complex data structures. 

While DataSnap still doesn't allow you to pass Del phi objects to and from 
server methods, what you can do istransform Delphi objects into an equivalent 
J SON representation and than back into actual objects. Thistechnique is called 
marshal i ng and is worth i nvestigati ng i n detai I . But before we get to that, let 
me start coveri ng one of the foundations, that is the J SON representation. 



I ntroducing J SON 

TheacronymJ SON stands forj avaScript Object Notation. This is a text-based 
notati on used to represent J avaScri pt obj ects 95 , so that they can be made per- 
sistent or transferred from one application to another (or from one computer to 
another). Whileafew years ago the consensus was for usingXML asa notation 
to represent complex data structures, in the last few years J SON has gained 
popularity becauseit is more compact, more tied to programming language 
concepts, and very easy to parse in J avaScript browser based applications... and 
by most other programming languages due to a growing set of libraries and 
tools. 

You can learn moreaboutj SON by reading the RFC 4627 specification of the 
I EFT (Internet Engineering Task Force) or looking at the official J SON home 
page: 

h 1 1 p : / / www. ietf.org/rfc/rfc4627.txt 
http://json.org 



95 More precisely, it is a subset of J avaScript's object literal notation. InJ avaScript, the use 
of double quotes around the pair name is not required for valid variable names. 
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You can also keep reading for a short introduction, asj SON is relatively simple 
to understand, with 4 primitive types and two structures. The primitive types 
are numbers, strings, Booleans 96 (true or false) and the null value. 

The two J SON data structures are: 

• J SON Objects- Collectionsof nameand valuepairs, enclosed in curly braces 
and separated by commas (whilethetwo elements of each pair are divided 
by a colon); collections represent records or objects 

• J SON Arrays- Lists of values within square brackets and separated by com- 
mas; lists represent arrays or collections 

Here are simple examples of the two notations, an object with two pairs (all 
strings including pairnames areindicated by double quotes) and a list of two 
values, a number and a string: 

{ 

"Name": "Marco", 
11 Val ue" : 100 

} 

[ 2 2 , " f o o " ] 

Of course, you can combi ne these constructs at wi 1 1 , so you can use objects and 
arrays as val ues of a pai r and as elements of an array: 

{ 

" Me " : { 

" F i r s t Na me " : " Ma r c o " , 
" L a s t N a me " : " C a n t u " , 
" Wi f e " : "Leila", 

"Kids": [ {" Na me" : " Benedet t a" , "Age": 10}, 
{" Name" : "J acopo" , "Age": 6} 



J SON in Delphi 2010 

While there have been afewj SON libraries for Delphi in the past, the first edi- 
tion with native support is Delphi 2010. ThenativeJ SON support has been 
made avail able through a series of classes defined intheDBXJ SON unit, which 
(despite the name) can be used even in applications that don't relate to the 
dbExpress framework. 



96 As we'll see later, Delphi treatsj SON Boolean values as two special values: true and false. 
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TheDBXJ SON unit defines classes that you can use to work with the various 
J SON data types (individual values of different types, arrays, pairs, and 
objects) all inheriting from T J SONVal ue: 

• PrimitivevaluesincludeTJ SONNul I ,TJ SONFal se,TJ SONTrue, 
Tj SONSt r i ng andTj SONNumber . 

• Data structures includeTJ SONObj ect (and the internal TJ SONPai r ) and 
Tj SONAr ray. 

H ere is a si mple code fragment, extracted from thej sonTests project, used to 
demonstrate the output of the different primitive types. Notice that each tem- 
porary object you create must be manually freed, hence the idea of adding the 
LogAndFree private support method: 

procedure TFor mj son. LogAndFree (jValue: TJ SONVal u e ) ; 
begi n 
try 

Log (j Val ue. CI assName + ' > ' + j Val ue. ToStri ng) ; 
finally 

j val ue. Free; 
end; 
end; 

procedure TFormJ son. btnVal uesCI i ck(Sender: T Object); 
begi n 

LogAndFree ( TJ S ONNu mb e r . Cr ea t e ( 2 2 ) ) ; 
LogAndFree (TJ SONSt r i ng. Create! ' samp I e text'))] 
LogAndFree (TJ SONTrue. Create) ; 
LogAndFree (TJ SONFal se. Create) ; 
LogAndFree (TJ SONNul I . Create) ; 
end; 

Thi s i s the correspondi ng output: 

TJ SONNumber > 22 

TJ SONSt r I ng > "sampl e text" 

TJ SONTr ue > true 

TJ SONFal se > false 

TJ SONNul I > null 

It is equally simpleto use theother classes of theDBXJ SON unit for creating 

arrays and objects. An array is a structure to which you can add any val ue 

( i ncl udi ng arrays and objects) : 

procedure TFormJ son. btnSi mpl eArrayCI i ck(Sender: TObject); 
va r 

j Li st : TJ SONAr ray; 
begi n 

j LI st : = TJ SONAr r a y . Create; 
j Li st . Add ( 22) ; 
j Li st . Ad d ( ' foo' ) ; 

j Li st.Add(TJ SonArray. Create ( TJ S ONTr ue . Cr e a t e ) ) ; 
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( j Li st . Get (2) as Tj SonAr ray) , Add ( 100) ; 
Log (jList.ToString); 
j Li st . Free; 
end; 

TheJ SON output shows the two nested arrays as follows: 

[22, 11 f oo" , [true, 100]] 

Note that thej SON containers (arrays and objects) own their internal ele- 
ments, so that you can free the contai ner to clean up the memory for the enti re 
group of J SON values. 

When you have an object, the only element you can add to it is a pair, but the 

value of the pair can bejust anyj SON value, including a nested object: 

procedure TFormJ son. btnSi mpl eObj ectCI i ck( Sender: T Object); 
va r 

j sonObj , subObj ect : TJ 5 ON Ob j ect ; 
begi n 

j sonObj : = TJ SONObj ect. Create; 

j sonObj . AddPai r ( T J SONPai r. Create ('Name', 'Marco')); 
j sonObj , Add Pa i r ( T J 5 ON P a i r. Create {'Value' , 
TJ SONNumber . Creat e( 100) ) ) ; 

subObj ect : = TJ SONObj ect. Create) 

TJ SONPa i r . Cr eat e ('Subvalue', 'one')); 
j sonObj . AddPai r ( T J SONPai r. Create ('Object', subObject)); 

Log (jsonObj.ToString); 
j sonObj .Free; 
end; 

TheJ SON representation of this object (with a little manual formatting to 
i mprove readabi I i ty) i s the fol I owi ng: 

{ 

11 Name" : "Marco", 
" V a I u e " : 10 0, 
"Object": { 

" Subval ue" : 11 one" 

} 

} 



Parsing J SON 

Creating J SON data structures using the DBXJ SON classes and generati ng the 
corresponding J SON representation is interesting, butitiseven more i nterest- 
i ng to know you can do the reverse, that is parse a string with aj SON 
representation to create the corresponding in memory objects. 
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Once you have a J SON string, you can passittotheParseJ SONVal lie class 
method of the T J SONObj ect , which returnsaTJ SONVal ue object 97 . Incases 
where we know the evaluation returnsaj SON object we have to cast it back to 
the proper type. The P a r s e J SONVal u e cl ass method doesn't accept a stri ng as 
parameter, but requires an array of bytes with an ASCI I encoding. So we need 
to take the stri ng and encode i t usi ng the TEncodi n g cl ass, that i s by cal I i ng 
TEncodi ng. ASCI I . Get Bytes . 

Overall, the initial portion of the bt nParseObj Click (still part of the mai n 
form of thej sonTests example) is the foil owing: 

v a r 

strParam: string; 
j sonObj : TJ SONObj ect ; 
begi n 

strParam : = ' { " v a I u e " : 3 } ' ; 

jsonObj := TJ SONObj ect. ParseJ SONVal ue( 

TEncodi ng. ASCI I . Get By t es ( s t r Pa r a m) , 0) as TJSONObject; 

The remai ni ng code outputs the enti re object (getti ng back the origi nal J SON 
representation, if nothing went wrong), thelast (and only) name/ value pair and 
frees theTJ SONObj ect object (again, it is easy to cause memory leaks with this 
type of code): 

Log (jsonObj.ToString); 

Log (j sonObj . Get ( j sonObj . Si ze - 1 ) . To St r i ng ) ; 
j sonObj .Free; 

Streaming Objects to J SON 

Now if it isthiseasyto createaTJ SONObj ect and add data to it, it would be 
very nice to create thej SON representation of any Delphi object. This is pos- 
siblein Delphi 2010 thanks to thej SON marshaling and de- marshaling 
support that is defined intheDBXJ SON Reflect unit. 

This unit defines an open and extensible marshaling architecture, and provides 
a specific implementation based on the internal TJ SONCon ver t er class. So, by 
default, you create a J SON marshal ler by passing thej SON converted to it: 

| j Marshal := TJ SONMarshal . Create(TJ SONConverter. Create) ; 



97 If you find it confusing that you haveto useaTJ SONObj ect class method to parse any 
J SON value and return a T J SONVal u e (which might bean object, an array, a primitive 
value) you are not alone. It seems quite a random pick to me. I think I 'd preferred a glob- 
al fundi on or a class method of theTJ SONVal ue class. 
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The marshaling engine will own the converter and free it when it is done by 
default. You can register more converters to support different formats, i nd ud- 
i ng XM L and others. The engi ne behi nd the marshal i ng support is the new 
Extended RTTI , which I covered in detail in Chapter 3. RTTI is used for saving 
an image of the objects (including all of the fields) and for re-creati ng a type 
given its name. The overall implementation is relatively complex and I don't 
really want to delve into the details, but only focus on a practical example. 

Let's suppose we have a class I ike this one defined inthej sonMarshal project 
(notice I 'm using private data and no published properties and the class is not a 
TPer s i stent class): 
type 

T My Da t a = class 
pr i vat e 

theName: String; 
the Value: Integer; 
publ I c 

constructor Create (const aName: string); 
function ToString: string; override; 
property Value: Integer read theValue write theValue; 
end; 

We can now wri te some code to create an obj ect of th i s cl ass, create the mar- 
shal ler, marshal it to a T J SONVal ue, and add the result to a Memo control: 

theData := T My Da t a. Cr eat e( ' j o h n ' ) ; 
t heData. Val ue : = 99; 

j Marshal := TJ SOMMarshal . Create(TJ SONConverter. Create); 
j Va I ue : = j Ma r s ha I . Ma r s ha I ( t he Da t a ) ; 
Memol, Li nes . Text := j Va I u e . To 5 1 r i n g ; 

I n the actual code this takes place within three nested try- finally blocks (omit- 
ted here), each freeing the obj ect created in the given step in reverse order: 

j Val u e . Free; 
j Ma r s ha I . Free; 
theData. Free; 

At the end of the operation the Memo control will have the J SON representa- 
tion of the obj ect created by converting the original Delphi object into its 
TJ SONObj ect equivalent: 

{ 

"type": " J sonMarshal _ Ma i n F o r m. T My Da t a " , 
" i d " : 1 , 
"fields": { 

" t h e N a me " : " j o h n " , 

11 1 heVal ue" : 99 

} 

} 
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To check if the operation was performed successfully, other than looking at the 

output you can check the H a s Wa r n i n g s function of the TJ SON Ma r s h a I class, 

with code like the following in which the j t f i e I d local variable used by the 

f o r - e a c h loop is of type TTransi entFi el d: 

if j Marshal . HasWarni ngs then 
begi n 

Me mo 1 . L i n es . Add ( s L i ne Br ea k + ' TJ SONMa r s hal warnings: '); 
for jtfield in j Marshal . Wa r n i ngs do 

Me mo 1, Lines. Add (jtfield. FieldNa me + ': ' + jtfield. TypeNa me); 

ThisJ SON representation can now be read into a TJ SONVal ue and this can be 
re-converted into the original Delphi object, by creating an object of the quali- 
fied type i ndicated at the very begi nni ng. The code is more or less the reverse of 
what we have j ust seen: 

jValue := TJ SONObj ect. Parse] SONVal ue ( 

TEncodi ng, ASCI I . Get Byt es ( Me mo 1 . L i ne s . Te x t ) , 0); 
jUnmarshal := TJ S ONUn Ma r s h a I . Cr e a t e ; 
anObject := j Un ma r s ha I . Un ma r s h a I ( j Va I u e ) ; 

Wecan now usethisobject I ike a native Delphi object: 

IShowMessage ('Class: ' + a n Ob j e c t . CI a s s Na me + 
sLi neBreak + anObj ect . ToSt r i ng) ; 



Jsonfvlarshal 



btnMarshal 



btnUnmarshal 



{ r type r : r :sonMarshal_MainForm.TMyData^d r :l, "fields' 
{'theNarne': 'johnny ','theValue': 199}} 



Jsonmarshal 



Class: TMyData 
johnny:199 



OK 



The output of this operation is visible in the next page. Notice that I edited the 
text of the memo to recreate an object with slightly different data. Attheend, 
remember to free all temporary objects (possibly in finally blocks): 
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a nObj ec t . Free; 
j U n ma r s h a I . Free; 
j Va I ue. Free; 



Using J SON Converters and Reverters 

TheJ SON marshaling support works great for basic types, but when data struc- 
tures become complex, you might want to customize the actual information 
that issaved. This is possible thanks to the ability of installing custom convert- 
ers and reverters which you can register for given classes and fields. The 
converters and reverters are implemented using anonymous methods 98 . 

Suppose, as an example taken from the samej sonM arshal demo, that you have 
a cl ass I i ke the fol I owi ng: 

type 

TDataWi thLi st = cl ass 
pr i vat e 

theName: String; 

theList: TStringList; 
publ i c 

constructor Create (const aName: string); overload; 
constructor Create; overload; 
function ToString: string; override; 
dest r uct or Dest roy; over ride; 
end; 

The constructors and destructors create and free the internal string list object. 
Noticethatweneed a parameter- 1 ess constructor as this is the one that will be 
invoked when the object is created through RTTI support. The constructor with 
the parameter, instead, initializes the string list with random numeric values. 

Now if we write code si mi lar to the previous portion of the example to create a 
J SON representation of the class, we'll get something like: 

{ 

"type": " J s o n Ma r s h a I _ Ma i n F o r m. T Da t a Wi thLi s t " , 
" i d " : 1 , 
"fields": { 

" t h e N a me " : " j o h n " , 
"theList": { 

"type": "Cl asses.TStri ngLi st", 
11 i d 11 : 2 , 
"fields": { 
■ FCount 11 : 10, 
" FCapaci ty" : 12, 



98 For detail on anonymous methods see my "Delphi 2009 Handbook". 
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" FSorted" : fal se, 

"FDupl i cates": "dupl gnore", 

"FCaseSensi ti ve":fal se, 

" F Own sObj ect" : fal se, 

" F De I i mi t e r " : " " , 

" F L i n e B r e a k " : 

" FQuot eChar " : " " , 

" F N a me V a I u e S e p a r a t o r " : " " , 

"FStri ctDel i mi ter": fal se, 

11 FUpdat eCount 11 : 0 

} 

} 

} 

} 

Sorry for the long listing, not terribly interesting, but I wanted to underline that 
there are all sorts of various private fields in theTSt r i n g L i st object, includ- 
ing many internal ones that make I i ttle sense (I ike the C a pac i t y ), but there is a 
si gn i f i cant omi ssi on : the el ements of the stri ng I i st are mi ssi ng! 

Not only will recreating this object cause an exception... but you'll even be 
unableto get back the actual data. The solution, as anticipated, isto customize 
thej SON output by defi ni ng a custom converter. You can convert a data struc- 
ture to anyTJ SONVal ue or map it to one that the marshaling layer can manage. 

I n this case I 've decided to convert theT S t r i n g L i s t object into an array of 

strings, which ishowaTL i s t Of St r i ng s is defined. This is the complete code 

for the marshaling operation: 

procedure TFormJ son. btnMarshal ConverterCI i ck( Sender: T Object); 
va r 

theData: TDataWithList; 
j Ma r s ha I : TJ SONMarshal ; 
jValue: TJ SONVal u e ; 
begi n 

theData := TDataWithList. Create! ' j ohn' ) ; 
try 

j Marshal := TJ SOMMarshal . Create(TJ SONConverter. Create) ; 
try 

j Marshal . Regi sterConverterfTDataWi t h Li st, ' f he Li st ' , 

function (Data: TObject; Field: string): TLi stOfStri ngs 
va r 

I : Integer; 
sList: TStringList; 
begi n 

s Li st : = TDataWi thLi st( Data) . theLi st; 
Set Lengt h (Result, s Li st . Count ) ; 
for I : = 0 to sLi st . Count - 1 do 
Resul t [ I ] : = sLi st [ I ] ; 
end) ; 

jValue := j Ma r s ha I . Ma r s h a I ( t he Da t a ) ; 
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try 

Memol. Li nes. Text := j Val ue. ToStri ng; 
finally 

j Va I ue. Free; 
end; 
finally 

j Ma r s ha I . Free; 
end; 
finally 

the Data. Free; 
end; 
end; 

NowtheJ SON representation for our object becomes: 



"type": "JsonMarshal Ma i nForm. TDataWi t h L i s t " , 
" i d " : 1 , 
"fields": { 

" t h e N a me " : " j o h n " , 

" t heLi st " : [ " 5 8 8 " , "31" , 11 6 5 6 " , " 4 8 9 " , 11 6 9 3 " , 
"631", 11 7 4 2 " , "816", "166", " 9 7 7 "] 

} 

} 

The opposite operation is performed by registering a reverter, another anonym- 
ous method, which will receive the array of strings and populate the 
TStri n g L i st object. Again, this is the complete de-marshaling code 

procedure TFormJ son. btnUnmarshal ReverterCI i ck(5ender: TObject); 
va r 

j Unmarshal : TJ SONUnMarshal ; 
jValue: TjSONValue; 
a nObj ec t : TObject; 
begi n 

j Val ue : = Tj SONObj ect . Parse] SONVal ue( 

TEncodi ng. ASCI I . Get Bytes (Memol. Lines. Text), 0); 
try 

jUnmarshal := TJ S ONUn Ma r s h a I . Cr e a t e ; 
try 

j Unmarshal . Regi sterReverter( TDataWi thLi st, ' f heLi st ' , 
procedure (Data: TObject; Field: string; 

Args: TList Of Strings) 
va r 

I : Integer; 
sList: TStringList; 
begi n 

s Li st : = TDataWi thLi st( Data) . theLi st; 
for I : = 0 t o Lengt h( Args) - 1 do 
sLi st. Add ( A r g s [ I ] ) ; 

end) ; 

anObject := j Un ma r s ha I . Un ma r s h a I ( j Va I u e ) ; 
try 

ShowMessage ('Class: ' + anObj ect . CI assMame + 
sLi neBreak + a n Ob j ec t . To S t r i ng ) ; 



Marco Cantu, Delphi 2010 Handbook 



Chapter 7: Database Access and DataSnap - 243 



finally 

a nObj ec t . Free; 
end; 
finally 

j Unmarshal . Free; 
end; 
finally 

j Va I ue. Free; 
end; 
end; 

J SON Values and Marshaling in DataSnap 
Server Methods 

Now that we know how to create a J SON value for different types and convert 
this representation to and from Delphi objects, we can apply itto a DataSnap 
server, defining methods that receive or returnj SON-based parameters and 
Delphi objects (using marshaling). 

The Server and the Client Applications 

The server class used by this example (a TCP/ 1 P based DataSnap server target- 
ingaTPe r s i stent class and called DSnapJ son) is the foil owing: 
type 

{ $METH0DI NFO ON} 
TDSnapJ sonMet hods = cl ass(TPersi stent) 
public 

function Si mp I e Va I u e : TJSONValue; 
function GetList (nElem: Integer): TJ SONArray; 
function Get Da t a (const strName: string): TJSONValue; 
end; 

{ $METH0DI NFO OFF} 

TheTJ SONVa I ue returned bytheSi mpl eVa I ue method is a plain value, while 
theTJ SONVal ue returned by theGet Da t a method is a marshaled instance of 
theT My Da t a class. This is the class I used in the earlier section "Streaming 
Objects to J SON" and it is defined in a separate unit, as I'll also need to compile 
the class in the client application, to be able to de- marshal thej SON data and 
rebuild the object. The third method returns a specific J SON data structure, an 
array orTJ SONAr ray. 

The client side application is a plain VCL program, which has an SQLConnec- 
tion component hooked to the server. I n this cl ient project, I 've created the 
client proxy for the server methods, which looks I ike the foil owing: 
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type 

TDSnapJ sonMethodsCI i ent = class 
pr i vat e 

FDBXConnect i on: T DBXCo n n ec t i o n ; 
F I n s t a n c e Owne r : Boolean; 
F Si mp I e Va I u eCo mma nd : T DBXCo mma nd ; 
F Ge t L i s t Co mma nd : TDBXCommand; 
F Ge t Da t a Co mma nd : TDBXCommand; 
publ I c 

constructor Cr eat e( ADBXConnect I on: T DBXCo n n ec 1 1 o n ) ; overload; 
constructor Cr eat e( ADBXConnect i on: TDBXConnecti on; 

Al nst anceOwner : Boolean); overload; 
destructor Destroy; override; 
function SimpleValue: TJSONValue; 
function Ge t L i s t ( n E I e m: Integer): TJ SONArray; 
function Get Dat a( st r Name: string): TJSONValue; 
end; 



Memory Management for J SON Values 

I n the proxy class there is an option to control the ownership of thej SON 
object instances (F I n s t a n c e Own e r ) being received from function calls, so that 
when you cal I a method and receive a T J SONVa I u e result you don't have to 
remember to manually free it. 

Likewise, when the server returns aj SON object it is DataSnap's responsibility 
to free the objects it has returned. That means that we don't have to worry 
aboutfreeingTJ SONVa I ue or derived objects on the server as well. 

What if you need to use these objects outside of the method that returned or 
received it? You can use the CI one method of TJ SONVa I u e , to create a new 
instance with the same value. For exampleon the server, if you need to return 
an object you still need to keep around, you can create and return a clone to 
that object, and the DataSnap infrastructure will take care of freeing the clone 
whilst you areresponsiblefortheoriginal object. 

Passing J SON Values Manually 

Now that I have covered the server side and cl ient side i nfrastructure, let me 

focus on the method cal Is one by one. The fi rst server method, Si mp I e V a I u e , 

returns a fixed and hand-crafted data structure, of type T J SONVa I ue: 

function TDSnapJ sonMet hods. Si mpl eVal ue: TJSONValue; 
begi n 

Resul t : = TJ SONObj ect . Create ( 

TJ SON Pa i r . Cr eat e ('name', 'Marco')); 
( Resul t as TJ SONObj ec t ) . Add Pa i r ( 

TJ SONPa i r . Cr eat e ('email', 'marco@marcocantu.com')); 
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The corresponding client calls (based on the proxy object) usethej SON Value 

directly (remember, no need to destroy it): 

procedure TFor mj sonCI i ent . bt nVal u e C I i ck( Sender : TObject); 
var 

jValue: TjSONValue; 
begi n 

jValue := Met hods Pr oxi . Si mpl eVal ue; 
Log (jValue.ToString); 
end; 

The result of this call isthej SON representation of thej SON data structure 
created on the server: 

{ " name" : " Mar co" , " emai I " : " mar co §ma r cocant u. com"} 

Returning an Array of Elements 

The second method returns a list of elements (in this case a list of strings) in a 

TJ SONAr r ay , that is created dynamically and returned: 

function TDS n a pj s o n Me t h od s . Ge t L i s t ( n E I e m: Integer): TJ SONArray; 
var 

I : Integer; 
begi n 

Resul t : = TJ SONArray. Create; 
for I : = 1 to nElemdo 

Resul t . Add( 'Item' +1 ntTOSt r ( I ) ) ; 

end; 

The cl ient passes the number of elements of the list, usi ng a plai n data struc- 
ture ( I coul d have used a T J SONNumber to pass the val ue, but better use the 
Integer type). This is a sample call, asking for an array with five elements: 

procedure TFormJ sonCI i ent. btnArrayCI i ck(Sender: TObject); 
var 

j Ar r a y : TJ S ONAr ray; 
begi n 

j Array := Met hods Pr oxi . Get Li st ( 5) ; 
Log ( j Ar r ay. ToSt r i ng) ; 
end; 

The output of this call is an array in itsj SON representation: 

["Item 1 " , " I t e m 2 " , " I t e m 3 " , " I t e m 4 " , " I t e m 5 " ] 

Passing a Marshaled Delphi Object 

The I ast method i s the most i nteresti ng one, as i 1 1 ets you move a Del ph i obj ect 
from the server to the client. What we are moving, infact, is the data of the 
object, not the code of its methods. These objects, in fact, must be compiled 
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(with the same structure) both in the client and the server, and the new Exten- 
ded RTTI must see same the class layout when it maps the object data to J SON 
and the J SON to the object data. 

Of course, this cannot be done directly, but requires the marshaling support 

I 've al ready covered i n the previ ous secti on . I n the server si de code of the 

Get Da t a method notice that while the memory for the returned J SON value is 

managed, you have to remember to free any temporary object and the marshal- 

ing object: 

fundi on TDSnapJ sonMethods. Get Da t a ( 

const strName: string): TJ SONVal ue; 
va r 

my Da t a : T My Da t a ; 
j Marshal : Tj SONMarshal ; 
begi n 

my Da t a := T My Da t a . Cr e a t e ( s t r Na me ) ; 
try 

j Marshal := TJ SONMarshal . Create(TJ SONConverter. Create) ; 
try 

Result := j Ma r s ha I . Ma r s h a I ( my Da t a ) ; 
finally 

j Ma r s ha I . Free; 
end; 
finally 

my Da t a. Free; 
end; 
end; 

I n case you want to pass complex data structures you'll have to register the 
proper converters, as covered i n the previ ous secti on about J SON . I n the cor- 
responding client call we have to de- marshal thej SON representation to obtain 
theoriginal Delphi object (provided theclass is indeed compiled into the client 
program) : 

procedure TFormJ sonCI i ent. btnMarshal CI i ck(Sender: TObject); 
va r 

jValue: TJSONValue; 
j Unmarshal : TJ SONUnMarshal ; 
my Da t a : T My Da t a ; 
begi n 

jValue := Met hods Pr ox i . Get Dat a ( '/ oe ' ) ; 
jUnmarshal := TJ S ONUn Ma r s h a I . Cr e a t e ; 
try 

my Da t a := j Un ma r s ha I . Un ma r s h a I ( j Va I u e ) as T My Da t a ; 
try 

Log ( myData. ToStri ng) ; 
finally 

my Dat a. Free; 
end; 
finally 
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j Unmarshal . Free; 
end; 
end; 

Again, the marshaling support objects and the actual Delphi object you re-cre- 
ate must be manual I y freed once you don't need them any more. The output 
shoul dn 't be su rpri si ng ( besi de the fact you 'I I get a di ff erent val ue for each 
object created on the server): 

j oe : 444 



Server Methods Callbacks 

One of the problems with server methods is that they might take some ti me to 
complete, thus blocking the client application which has no way to figure out if 
there i s any work i n progress or the server i s j ust stuck. 

While covering DataSnap in my Delphi 2009 Handbook, I wrote an example 
showing the advantage of encapsulating the client call in a thread, so that even 
if the server takes time to respond and we don't know what is going on, at least 
the user interface of the client application remains responsive. In the opposite 
case, not usi ng threads, the user i nterface freezes unti I we get a response (or a 
ti me-out error) . You' 1 1 fi nd the source code of this threaded example i n the 
DsnapMethodsCal I back example", which extends the program written for 
Delphi 2009. 

What is new in DataSnap in Delphi 2010 isthe ability to send information from 
the server back to the cl ient whi le it is waiti ng for a response. A cal I back i n 
DataSnap is not a mechanism to let the server call the client at will (also 
because this would make very little sense in case of a stateless HTTP commu- 
nication layer), but it is limited only to the execution of the server method 100 . 



99 The example is somewhat complex, and hasaclientcapableof startinga local instanceof 
the server with different session lifetime configurations. Here I won't describe all of the 
features of the program in details but focus only on the specific issue, calling a slow serv- 
er method. 

100 In theory, one could write a very long or even infinite server method, which will let the 
server keep cal ling the client indefinitely. I 'm not convinced this is a great idea in gener- 
al, compared to letting the client poll the server at regular intervals, but there might be 
specific situations in which infinite server methods with a cal I back come in handy. 



Marco Cantu, Delphi 2010 Handbook 



248 - Chapter 7: Database Access and DataSnap 



The Server Side I mplementation of a Callback 

Having clarified the scope, let us look at the actual implementation. On the 
server, the server class is declared as: 
type 

{$Met hodl nf o ON} 
TSi mpl eServerCI ass = classfTPersi stent) 
public 

function Echo (const Text: string): string; 
function SlowPrime (MaxValue: Integer): Integer; 
function SI owPri meCal I Back (MaxValue: Integer; 
aCal I Back: TDBXCal I back) : I nteger; 

end; 

{$Het hodl nf o OFF} 

As you can see there istheoriginal SI owPri me function, which takes several 
seconds to execute, and the SI owPri meCal I Back version with the call back 
parameter. It is this new one I am focusing on here. 

The server method recei ves as extra parameter, an obj ect i mpl ementi ng the 
TDBXCal I back class and can use its Execute method to send i nformation back 
to the client while the original function call is still taking place. This isthe 
declaration of the virtual abstract method of theTDBXC a I I back class: 
type 

TDBXCal I back = cl ass abstract 
public 

function Exec ut e( const Arg: TJSONValue): 
TJ SONVa lue; virtual; abstract; 

As the server passes some data back to the cl ient, it receives a return val ue. You 
can useitasyou like, but the general idea is to use the return value of the 
Execute method of the call back to let the client application ask the server to 
"stop the execution". That is, while the server is processing, it can tell the client 
it is progressing along and ask whether to continue or not. 

Thisapproach provides a nice way to let the user of the client application press 
aCancel button in case the operation istooslow, notify the server and ask the 
server to stop the long operation. The standard implementation is to use the 
TJ SONFal se value to ask the server to stop. 

This is also the approach used by the SI owPr i meCal I Back function, which 

checks foraTJ SONFal se return value: 

functi on TSi mpl eServerCI ass. SI owPri meCal I Back( 

MaxValue: Integer; a C a I I Back: TDBXCal I back) : Integer; 
va r 

I : Integer; 
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j sonResul t : TJ SONVal ue; 
i s F a I se: Bool ean; 
begi n 

// counts the prime numbers below the given value 
Result : = 0 ; 

for I : = 1 t o Ma x V a I ue do 
begi n 

if I s P r i me ( I ) then 

I nc (Result); 
if (I mo d 10 0) = 0 then 
begi n 

j sonResul t := aCal I Back. Execute( TJ SONNumber. Create( I ) ) ; 
IsFalse := j sonResul t is TJSONFalse; 
j sonResul t . Free; 
if IsFalse then 
Break; 

end; 
end; 

aCal I Back. Free; 
end; 

Every 100 cycles in theloop (calling back the client for every single cycle would 
beoverkill) theprogramcallstheExecut e method. Notice that both the call- 
back object and the parameter returned by executing the call back must be freed 
manually, or you'll experience a memory leak. 

The code has an extra intermediate variable, i s F a I s e , as I cannot break out of 
theloop before freeing the TJ SONVal ue object and I cannot check its value 
after it has been destroyed. 



The Client Side I mplementation of a Callback 

This is all you have to do on the server. On the client side, on the other hand, 
you have to provide an actual implementation of theExec ut e method, provid- 
ing an actual implementation for the virtual abstract class: 
type 

TMyCal I Back = cl assfTDBXCal I back) 
pr i vat e 

f Label : TLabel ; 
publ i c 

constructor Create (aLabel: TLabel); 
function Exec ut e( const Arg: TJSONValue): 
TJ SONVal ue; over ride; 

end; 

The actual code is in theExec ut e method, which updates a label displaying the 
current status, lets the cl ient appl ication process Wi ndows messages (thus 
avoiding freezing the user i nterf ace even without using a thread), and returning 
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the indication whether the server can keep going (TJ S 0 NT r ue ) or should stop 

(Tj S ON F a I se): 

function TmyCal I Back. Execute) 

const Arg: Tj SONVal ue) : Tj SONVal ue; 
begi n 

f La be I . Caption : = Arg.ToStri ng; 
Appl i cati on. Process Me ssages; 

if f Label . Tag = 0 then 

Resul t : = TJ SONTrue. Create 
else 

Result : = TJ SONFal se. Create; 

end; 

The main form usethelabel'sTag to communicate with the object implement- 
i ng the cal I back. Thi s i s set to zero before starti ng the cal I ( see the comi ng 
listing of thebt n P r i me s C a I I CI i c k method) and set to one as the user clicks 
on the label itself. 

With this class available, all you have to do on the client side, when you call the 

server method 101 , is to pass an instance of the cal I back implementation: 

procedure T F o r mD smcCI i ent. btnPri mesCal I CI i ck( Sender: TObject); 
begi n 

if not Assigned ( S I mp I e Se r v e r ) then 

SimpleServer : = T S i mp I eServerCI assCI i ent. Create ( 
SQLConnectl onl. DBXConnectl on); 
I bl Pr I mes Ca I I . Tag : = 0; // reset 
IblPrl me sCall. Caption : = IntToStr ( 

SI mpl eServer. SI owPrl me Cal I back ( Spl n E d i 1 3. Val ue, 
T My Ca I I Back. Create ( I bl Pri mesCal I ) ) ) ; 

end; 

Now we can run the program and test if it works. You can si mply start the 
server, start the client, and press the b t n Ne wF o r m button to open an actual cli- 
ent form with a connection. 

From the client form you can call the slow server side method in a standard 
blocking way (thebt nPr i mes button), use the cal I back (thebt nPr i mesCal I 
button), or within a thread (thebt n Pr i mes Th button). In case of the cal I back, 
you can click on the label next to the button to stop server side processing. The 
server logs the request, so you can better understand what is goi ng on. 



101 In this application I 'm using the DataSnap client proxy to call the server methods, as is 
much better than relying on data set parameters for complex cal Is. 
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The server form is visible here on the right, while on the I eft there is the Main 
cl i ent form al ong wi th the actual CI i ent form of the cl i ent with the con necti on 
and the button to call server methods. 
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What's Next 



Now that we have explored DataSnap in some detail, there is one area of this 
architecture that I mentioned and didn't delve into. This is the REST support 
offered by DataSnap and tied to itsj SON support. 

If REST architectures are generally quite simple to understand, using REST in 
Delphi opens up communication with many online services and the ability to 
provide the back-end to J avaScript browser- based applications. Rather than 
focusing exclusively on new features of Delphi 2010, in the last chapter of the 
book I'll open up the coverage to one of the fastest growi ng areas of today's 
technology, namely cloud and service-based architectures. 
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Chapter 8: REST 
Web Services 

Over the last few years, there has been a large expansion of and a significant 
shift around web services. Promised asanewwayfor applications to interact 
and exchange data, web services have long been synonymous with the SOAP 
technology behi nd them, but have been quite slow to catch up with thei r prom- 
ises. The recent expansion in web services, both as a way to interact with major 
web sites and with remote applications, is mostly due to a competing techno- 
logy called Representational State Transfer, generally referred to as REST. 

In this chapter I'll introduce REST to you, focusing on how it is supported in 
Delphi 2010 and opening up the coverage to the development of client REST 
applications and to building REST servers in Delphi with a direct, manual 
approach not based on DataSnap. 

I 'II also cover afew Delphi 2010 related topics, I ike the support for version 12 
of the SOAP standard and i improvements i n the native XM L processi ng sup- 
port, and other topics tied to REST but not specifically to Delphi 2010, like 
XML processing techniques and J avaScript development. I won't delve into the 
J avaScript language by itself, but focus on the use of the j Query library. 
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Why Web Services? 

The rapidly emerging web services technology has the potential to change the 
way the I nternet works for busi nesses. Browsi ng web pages to enter orders is 
fine for individuals (business-to-consumer applications) but not for companies 
( busi ness-to- busi ness appl i cati ons) . I f you want to buy a few books, goi ng to a 
book vendor's website and punching in your requests is probably fine. But if 
you run a bookstore and want to place hundreds of orders a day, this is a far 
from efficient approach, particularly if you have a program that helps you track 
your sales and determine reorders. Grabbing the output of this program and re- 
entering it into another application is ridiculous. 

Web services are meant (or to be more precise were originally meant) to solve 
this issue: The program used to track sales can automatical ly create a request 
and send it to a web service, which can immediately return information about 
the order. The next step might be to ask for a tracki ng number for the ship- 
ment. At this poi nt, your program can use another web service to track the 
shipment until it is at its destination, so you can tell your customers how long 
they have to wait. As the shipment arrives, your program can send a reminder 
viaSMSor pager or Twitter to the people with pending orders, issuea payment 
with a bank web service, and... I could continue but I think I've given you the 
idea. Web services are meant for computer interoperability, much as the Web 
and e-mail let people interact. 

The topic of web services is broad and involves many technologies and busi- 
ness-related standards. As usual, I'll focus on the underlying Delphi 
implementation and the technical side of web services, rather than discuss the 
larger picture and business implications. Delphi for Win32 offers some rather 
sophisticated support for web services, which originally came in the form of 
SOAP, and can now easily be extended by means of HTTP components and 
REST. 



Web Service Technologies: SOAP vs. REST 

The idea of a web service is rather abstract. When it comes to technologies, 
there are currently two main solutions that are attracti ng developers. One is the 
use of the SOAP standard (Simple Object Access Protocol, see the reference site 
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ath 1 1 p : / / www. w3 . org/TR/ soap / ), another is the use of a REST (Represent- 
ational State Transfer) approach, along with its variation XML-RPC (XML- 
Remote Procedure Cal I ) . 

What is relevant to noticeisthat both solutions generally useHTTP as the 
transmission protocol (although they do provide alternatives) and use XML (or 
J SON ) for movi ng the data back and forth. By usi ng standard HTTP, a web 
server can handle the requests, and the related data packets can pass though 
fi rewalls. 

In this chapter I won't provide many details on SOAP (with the exclusion of 
mentioning new features added to Del phi 2010), but focus extensively on 
REST. I 'II start by providing some theoretical foundations, show a simple 
"hand- made" example of a server and a client, delve into the development of 
REST cl ients for popular REST web services and focus on the REST server side 
support available in Delphi 2010 as an extension of the DataSnap architecture. 



XML and SOAP Updates 

Before I start focusi ng on REST and companion technologies, let me cover a 
coupleof relevant Delphi 2010 updates that relate to Web Services in general. 
The first is the improved support for XML processing, with updates in MS XML 
DOM mapping and in the version of the native OpenX ML library that ships 
with the product. The second is the extension in SOAP support, specifically 
compatibility with version 12. 

XML Processing in Delphi 2010 

Del phi 's overal I support for XM L processi ng has not changed i n any radical 
way, with support for DOM 102 manipulation taking pi ace through theXMLDoc- 
ument component. This component offers the standard DOM i nterface, a 



102 DOM stands for Document Object Model and isa standard for navigating a document 
represented asatreeof nodes. The DOM interface is a standard, even if very low- level 
way, to access documents such as an X M L document or the H TM L data of a page i nsi de a 
browser. 
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higher level XML DOM, and interface binding through the XML Mapper tool. 
This component can interface with multipleXML DOM engines, some of which 
have seen significant improvements, as covered below. 

Beside these important changes in the XML DOM libraries that are most used 
in Delphi applications, there are also improvements in the XML Data Binding 
wizard, which now handles the include element of schema files. 

Microsoft XML DOM Version 6 

Themsxml unit interfacing Microsoft XML DOM (and available in the 
s o u r c e\ Wi n 3 2\ r 1 1 \ wi n folder) now refers to version 6 of the XML engine 
(msxml6.dll). Differently from the past 103 , the unit now includes almost all 
interfaces, including the VB version of the SAX interface. 

The unit with all interfaces is called msxml and its source code can be found 
under thes ource\Win32\rtl\win folder and notthes o u r c e\ Wi n 3 2 \ x ml 
folder, which hosts the DOM mappers, including the msxml dom unit for MS 
XML DOM mapping from theXMLDocument component. 

As this is the library used by the Del phi IDE, its improvements also relate to the 
XM L- related tool set of Delphi. 

The Alternative Document Object Model 

The Pascal native XML engine, written and maintained by Dieter Kohler, has 
been upgraded to the much newer version 4.3 (it had remain at version 2.3.14 
for many years). The new library has also a different name: from "Open XML" 
it is now "Alternative Document Object Model". Along side this change, the 
vendor name in theXM LDocument component was updated to "ADOM XM L 
v4", so you'll have to update any application using it. 

This also implies a change in the unit structure, potentially causing incompat- 
ibilities. In the past there was only one unit (xdom), now there is a dozen of 
them (the mai n one bei ng AdomCore_ 4_3). If you have delved i nto this I i brary, 
of course, you'll see some quite radical changes. 



103 I n the past you had to generate these i nterfaces by i mporti ng the type I i brary, as I d i d 
many times in the past for working with the SAX interface (covered by an example in 
Mastering Delphi 2005). Note, by the way, that you have to use the VB version of the 
SAX i nterface, because the C++ versi on i s broken at the type I i brary I evel . 
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Updating My LargeXml Application 

To better figure out the effect of theXM L- related changes, I 've decided to 
upgrade an X ML- processing application I wrote for the Mastering Del phi book 
series, called LargeXml, to Delphi 2010. This program uses both MSXML and 
ADOM , and their SAX interfaces quite extensively. 

In short, the application connects to a database, generates CI ientDataSets with 
a lot of data, and saves them to XML files with different techniques (direct 
Xml Dat a content of the component, XML mapper, manual creation of the XML 
format). The second feature of the demo, which is the one I 'II focus on here, is 
to ability reopen these XML documents either in a DOM or by parsi ng them 
and filling a second ClientDataSet. The original parsing style was SAX M4 . 

The first think I had to do was to change the reference to OpenXM L to ADOM 

XML in one of the Xml Document components: 

lobject XMLDoc ument 2 : TX ML Do c u me n t 

DOMVendor Desc = 1 ADOM XML v 4 ' 
lend 

Nextl had to make quite a few changes in the uses statements, replacing: 

• thexdom unitwiththeAdomCore_4_3 unit 

• the oxmldom unit (for using the Open XML DOM with the XMLDocument 
component) with the new adomxmldom interfacing ADOM 

• theMSXML2_TLB interface unit with the ready to usemsxml unit. 

The other problem was that (at least in my installation) most of the units 
related to XM L support are not avai I able in d c u format i n the I i b folder, so I 
had to i ncl ude thei r source code folder i nto the project Search path. 

Next I had to fix the streami ng code to support U nicode, for example changi ng 

theT F i I e S t r e a m based code to usetheT S t r e a mWr i t e r class introduced in 

Delphi 2009. This is an example of the new codi ng style: 

procedure TForml, btnSaveXml Packet CI i c k ( Sender: TObject); 
va r 

sWriter: TStrea mWr iter; 
begi n 

sWriter := TStrea mWr i ter. Create ( ' dat a. xml ' , False {replace}); 
try 

s Wr i t er . Wr I t e ( CI I ent Dat a Set 1. XML Dat a) ; 



104 SAX, or Simple API for XM L, is an event driven parsing technology. For each element of 
the XML file being parsed, the SAX engine will trigger an event (technically call a virtual 
method) which is up to to program to process or discard. 
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finally 

sWri ter. free; 
end; 
end; 

The code for MS SAX support worked with basically no changes, as my original 
code used the VBSAX i nterfaces obtai ned by i mporti ng the type I i brary ( prob- 
ably of MS XML version 4 at the time). All I had to do was change the name of 
the Set_documentLocator method to_Set_documentLocator, addi ng the 
initial underscore. 

For the code in the ADOM XML I didn't find any equivalent to the original 
SAX-likesupport, so I basically had to rewrite that using the new signals-based 
coding style. The core of the parsing code is the in Pr oc es s S i gnal method of 
theTXml St andardHandl er derived class, which provides the custom imple- 
mentation for the parsi ng code. 

I n this code the program handles three events (or signals). As it hits the start of 

an XM L node (T X ml St ar t El e me n t Si gnal ), the program adds the node to a 

local stack (a string list) and when this is a new employee record it calls the 

I nsert method of the target CM entDataSet component. The program keeps 

adding any textual elements (TX ml PCDATASi gnal ) to the current text, which 

might bedivided among multiple nodes. When it hits the end of an XML node 

(TXml End El ement Si gnal ), if it was reading an XML node at level 3 of nesting 

the program adds the text that was read to the corresponding field of the CM - 

entDataSet, whi le if this is at the end of the record, it posts the data: 

procedure TDataSaxHandl er. ProcessSi gnal (const Signal: T X ml Si gnal ) ; 
va r 

tagname: string; 
begi n 

if Signal is TXml StartEl e me n t S i gnal then 
begi n 

stack. Add (TXml StartEl ementSi gnal (SI gnal ).TagName); 

if TXml StartEl ementSi gnal (Si gnal ).TagName = 'employee Data' then 

For ml . cl i entdataset2. I nsert; 
strCurrent := 11 ; 
end 

else if Signal is TXml EndEI ementSi gnal then 
begi n 

if TXml EndEI ementSi gnal (Si gnal ).TagName = ' empl oyeeDat a' then 

Forml.cllentdataset2.Post; 
if stack. Count > 2 then 
begi n 

For ml. CI I ent Dat aSet 2. Edi t ; 

For ml. CI i ent Dat aSet 2. Fi el d By Name ( 

TXml EndEI ementSignal (Signal ).TagName). 
As String : = strCurrent; 
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end; 

stack. Del ete ( stack. Count - 1) ; 
end 

else if Signal is TXml PCDATASi gnal then 
begi n 

strCurrent := strCurrent + RemoveWhi tes( 
TXml PCDATASi g na I ( S i g na I ) . Da t a ) ; 

end; 
end; 

Also the code to invoke this si gnal -based processing is slightly different from 

the original code used to invoketheSAX engine. Itsessenceis: 

reader: = TXml StandardDocReader. Create (nil); 

r ea de r . Ne xt Ha nd I e r := T Da t a S a x Ha nd I e r . Cr ea t e (nil); 

SourceStream := TFi I eStream. Create(Fi I ename, f mOpenRead) ; 

Sysld : = Fi I enameToUri Wi deStr( Fi I ename, []); 

i nputSource : = TXml I nputSource. Create( SourceStream, 

", Sysld, 4 0 9 6, ", False, 0, 0, 0, 0, 1); 
reader. Parse (i nputSource); 

Now if you've never used a SAX engine this code and description might seem a 
little awkward, but I felt it relevant to mention the change and show some 
demo code to everyone who used this XML library (maybe foil owing my very 
own advice!). 

SOAP 1.2 Support 

Even if I think REST interfaces are on the rise and SOAP its in decline, there 
are significant environments (from governmental bodies to large companies) 
who mandate the use of SOAP as a way to communicate with them. That's why 
good quality SOAP support remains an important Delphi feature. 

I n the new version, Delphi adds support for the development of SOAP version 
12 clients, which conform to the standard. You can now import newer WSDL 
files and generate the Object Pascal i nterfaces for newer services. I have done 
very limited testing of this aspect. 

Note that SOAP support is now formally limited to the development of clients: 
building SOAP servers in Delphi isstill possible but the technology has been 
deprecated . F i nal I y, there i s another mi nor but potenti al I y i nteresti ng opti on , 
which is support for HTTPS requests authenticated using an X509 certificate. 
This is available using a new I nvokeOpt i on of the HTTPRIO component, 
soP i ckF i rstCI i entCerti f i cate. 
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What is REST? 

Even if the general idea of REST has been around for sometime, theintroduc- 
tion of thisformal name and the theory behind it are fairly recent. What is 
relevant to mention up front is that there isn't a formal REST standard. 

The term REST, an acronym for Representational State Transfer, was originally 
coined by Roy Fielding in his Ph.D. dissertation in year 2000, and spread very 
rapidly as a synonym for accessi ng data over the web usi ng HTTP and U RLs, 
rather than relying on the SOAP standard. 

The term RE ST was originally used to describe an architectural stylewhich 
described the relationship of a web browser with a server. The idea is that when 
you access a web resource (either usi ng a browser or a specific cl ient appl ica- 
ti on) the server will send you a representation of the resource (an HTML page, 
an i mage, some raw data. ..). The cl i ent recei vi ng the representati on i s set i n a 
given state. As the cl ient accesses further i nformation or pages (maybe usi ng a 
link) its state will change, transferring from the previous one. In Roy Fielding's 
words: 

"Representational StateTransfer is intended to evoke an image of how 
a well-designed Web application behaves: a network of web pages (a 
virtual state- machine), wheretheuser progresses through an applica- 
tion by selecting links (state transitions), resulting in the next page 
(representing the next state of the application) being transferred to 
the user and rendered for their use." 

REST Architecture's Key Points 

So, if REST is an architecture (or even better, an architectural style) it is clearly 
not a standard, although it uses several existing standards I i ke HTTP, URL, 
pi us many format types for the actual data. 

While SOAP replies on HTTP and XML but builds on those, REST architectures 
use HTTP and XM L (or other formats) exactly as they are: 

• REST uses URLs to identify a resource on a server (while SOAP uses a single 
URL for many requests, detailed in the SOAP envelope). Notice theidea isto 
use the URL to identify a resource not an operation on the resource. 
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• REST uses HTTP methods to indicate which operation to perform (retrieve 
or HTTP GET, create or HTTP PUT, update or HTTP POST, and delete or 
HTTP DELETE). 

• REST uses HTTP parameters (both as query parameters and POST paramet- 
ers) to provide further information to the server. 

• REST relies on HTTP for authentication, encryption, security (with HTTPS). 

• REST returns data as plain documents, using multiple mi me formats (XML, 
J SON, images, and many others). 

There are quite a few architectural elements that are worth considering in this 
ki nd of scenario. REST demands for systems to be: 

• Client/ server in nature (nothing directly to do with databaseRDBMS here). 

• I nherentl y statel ess. 

• Cache-friendly (the same URL should return the same data if called twice in 
sequence, unless the server side data changed), permitting proxy and cache 
servers to beinserted between the client and the server. A corollary isthat 
all GET operations should have no side effect. 

There is certai nly much more to the theory of REST than this short section 
covered, but I hope this got you started with the theory. The practical examples 
coming next along with Delphi code should clarify the main concepts. 

The REST Architecture and Delphi 

Having said that there is no REST standard and that you need specific tools for 
REST development, there are existing standards that REST relies upon and 
that are worth introducing (an in-depth description of each could take an entire 
book). The specific focus hereis Delphi support for these technologies. 

HTTP, Client and Server 

The H yperText Transfer Protocol is the standard at the heart of the World Wide 
Web, and needs no introduction. Granted, HTTP can be used by Web Browsers, 
but also by any other application. 

I n Del ph i appl i cati ons the si mpl est way to wri te a cl i ent appl i cati on that uses 
HTTP is to rely on thelndy HTTP client component, or IdHttp. If you call the 
Get method of this component, providing a URL as parameter, you can retrieve 
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the content of any Web page and many REST servers 105 . At ti mes, you might 
need to set other properties, providing authentication information or attach a 
second component for SSL support (as we'll see in some examples). The com- 
ponent supports all HTTP methods, in addition to Get . 

On the server side you can use multi pie architectures for creati ng a web server 
or web server extension in Delphi. For a stand-alone web server you can use the 
IdHttpServer component, whilefor creating web server extensions (CGI applic- 
ations, I SAPI , or Apache modules) you can use the WebBroker framework. 
Another new option isgiven by the HTTP support within DataSnap in Delphi 
2010. 1 parti ally covered that in the last chapter and will focus on itinthisone. 

XML 

Extensible M arkup Language is a commonly used format for data, although 
many REST servers use alternative data structures likej SON (J avaScript 
Object Notation) and at times even plain comma-delimited text files. Again, 
XM L is widely used and I don't want to cover it in detail here. 

In Delphi, you can processXML documents using the XMLDocument compon- 
ent, as covered in the earlier section on Delphi XML updates. The 
XMLDocument component isa wrapper around one of the avail able XML 
DOM engines (the default one being Microsoft XML DOM). Once a document 
is loaded you can navigate its node structure or query the document using 
XPath (which is often the style I prefer). 

XPath 

XPath is a query language that lets you identify and process the nodes of an 
XML document. The notation used by XPath resembles file system paths 
(/ root / nodel / node2) with square brackets added to express conditions on 
nodeattributesorsubnodes(root/ n o d e 1 [ @v a I =5] ) or even complex expres- 
sions. The result of an XPath statement can itself bean expression, likethe 
number of nodes matching a ruleor the total value of a set of nodes. 



105 Notice that to be on the safe side you should generally make I dHttp requests inside a 
thread, as I ndy uses blocking threads: the user interface of your program will be stuck 
until the requests are returned (which take a long time in case of a slow web server or a 
large data transfer). I won't generally use threads in the demos in this chapter, that is 
onlyfor the sakeof simplicity. I strongly recommend the use of threads in live applica- 
tions. 
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In Delphi you can execute an XPath request by applying it to the DOM hosting 
the document, if the specific DOM supports it. We'll see an example of XPath in 
thefi rst REST client demo. 



REST Clients Written in Delphi 

There are countless examples of REST servers that you can fi nd on the Web. 
Even if the number of web services that uses REST on the I nternet is high, most 
actual web servi ces requi re some developer token (as covered i n some of the 
coming demos), while only a handful offer totally free and open access. For a 
much longer list of Delphi REST clients that I have written, you can refer to the 
specific section of one of my web sites: 
| http: / / a j ax. marcocantu. com/ del phi rest 

You can also find more coverage of REST clients written in Delphi inthe paper 

on REST that I wrote for Embarcadero Technologies, which is based on the 

material of this chapter: 

http:// www. embarcadero - i nfo. com/ i n _ a c t i on/ 
radstudi o/rest. html 

I n this chapter I 'II cover only a few selected examples: a first demo of accessing 
RSS feeds (which uses XM L and XPath), two mappi ng demos (based on differ- 
ent return types), and a translation examplewhich usedj SON. 

A REST Client for RSS Feeds 

The most widespread format for distri buti ng i nformation as XM L is the use of 
the RSS and ATOM feeds, mostly attached to blog and news sites, but equally 
usable for any data source. 

The i nteresti ng poi nt about feeds i s they provi de the same i nfor mati on to cl i ent 
applicationsthatauserwill generally access using a web browser. Feed inform- 
ation is processed by these client applications, and at times even combined in a 
summary of similar feeds, as happens on the Delphi Feeds site: 

| ht t p: / / www. del phi f eeds .com 
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That's why, as a first example of a client application using REST, I wrote a very 
simple RSS client 106 looking into blogs at this site. Every time you access 
dynamic XML data using an URL and you can change the URL to access differ- 
ent data, you are using the REST approach. TheRssClient program uses an 
IdHttp component and an XMLDocument component. The first component is 
used to grab the data from the Web and load it i n the second component: 
v a r 

s t r X ml : string; 
begi n 

strXml : = I dHTTPl. Get 

( 'http: //feeds, del phi feeds, com/ del phi feeds'); 
XMLDocument 1. Load Fr omXML( st rXml ) ; 

Thedata extracted would look like the following (which I've somewhat simpli- 
fied for readability), when displayed in an XML editor: 



4} XML Typist [ ] 

hie Edit SMrch DcKumenC OotScrvn XSL GXI Hd^ 

6fc!^y& \ * Q J • > O Er a ■ & * w 

_J UritibMTI | 

<rss sanlns : fe^dburner= 1T Kttp: //rssnamespace. org/f eedburner /ex t/l_G" vers i on- n 2.0 ni > 
-cchanne1> 

*ti 1 1 e> Del phi Feeds . cam< / 1 i 1 1 e> 

<1 i nk> http : //www. del phi feeds . c omA / 1 ink> 

<description>All Delphi blogs directly from DelphiFeeds . cojn</description> 

< 1 anguago en-us< / language 

< managi ngE di tar> teanidelph i feeds . com foe 1 phi Feeds .com Team) < /managi ngLdi tor> 
<webMaster>team0delphif eeds . com (DeT phi Feeds .com TeanO</webMaster:> 

< i mage> 

ctitle> Del phi Feeds ,con</t itle> 

<url>http://www_delphifeeds . rom/sr/df 1 .png* /url> 
< 1 i nk>h ttp : //www. del ph i feeds . com/</ 1 i nlc > 
<wi<fth> ll5</nri dth> 
<height>30< /hei gh _ t> 
desc n" pi ion -Delphi Feeds . com - All [>elphi blogs in one p 1 ace. ^/descript ion> 
</image> 

<atofliLO: 1 ink xmlns:atoTnlO='" http: //wmt. w3 . orq/ZOOS/Atofn"" re 1 = "'.sel f " href="http:/ 
<f eedburner : emai 1 Serviceld>del phif eeds</ feedburner : ernai lServi-celd> 
<f eedburner: f eedbumerHostnamo ht tp: //feedburner, goog le . com* / f eed burner : f eed-bu r 
<at ami 0: link xml ns : atojTilO= HH http: //www. w3 , orq/2005/Atom"' rel="'hub M href = " http:// 
<i t.em> 

<title> < I [COATAfDynam fc arrays £€" pure reference types, except when theya€ x r 
<1 ink>h ttp: //feeds .del phi f eeds.com/~r/del phi feeds /~3/50DPutx_M Q/634 30-e/l ink> 
<pubDate>Wed. 9 Dec 2009 IS: 40: 26 fO10<J*:/pubDate> 
<author> <jf [CDA TA [Delphi Haven (CR)) ]></ authors 

^descriptions reasonable way to understand the semantics of dynamic arrays i 
-quid isPermaLi nk- "'false" x'/^C^i TA [http: //www. de Iphi 'feeds . com/go/f/634 30Jj[xJ 
<f eedburner : or igl_imk> http: //www. del phi feeds .com/go/f /634 30< /feedburner : origLi 
<Yi tem> 



Processing the RSS Data with XPath 



To extract the relevant information from this XM L document the RssClient 
program uses XPath expressions. For example it reads the title of thefirst blog 
post (item) of the list uses the expression / r s s / c hannel / i t em[ 1] / 1 i 1 1 e . 



106 A video of the development of this Delphi client application step-by-step and its final res- 
ult is available on YouTubeat http://www.youtube.com/watch7v434cmBrqVRI A and in 
my bl og at http:/ / bl og. marcocantu .com/ bl og/ rest_ del ph i_ cl i ent_ vi deos. html . 
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This isdonein acyclealong with the extraction of some other information, 
formatted and di spl ayed i n a I i st box. U si ng X Path requi res the use of a custom 
i nterf ace of the M i crosoft engi ne: hence the cast tol DOMNodeSel ect . 

Once it has the nodes it is i nterested in, the program looks for any chi Id text 
node, usingaget Chi I dNodes helper function I wrotefor this purpose, and 
adds the data to a I ist box. This is the complete code of the method executed 
when the U pdate button of the program is pressed: 



r o c e 


d u r 


e TRssForm. btnUpdat 


eCl 


ickfSender: TObject); 


3 r 










st r 


Xml 


, title, author, pu 


b Da 


t e : string; 


1 : 


1 nt 


eger ; 






1 Do 


mSe 


1 : 1 DOMNodeSel ect ; 






Nod 


e : 


1 DOMNode; 






egi n 










st r 


Xml 


: = 1 dHTTPl. Get 






( 


•fit 


f p: 1 1 f eeds . del phi f e 


eds 


. com/delphifeeds'); 


XML 


Doc 


u ment 1. LoadFr omXMLf 


st r 


Xml ) ; 


XML 


Doc 


u me ntl. Active : = Tr 


ue; 




1 Do 


mSe 


1 :=( XML Document 1. 


Doc 


ument El ement . DOMNode 


a 


s 1 


DOMNodeSel ect ) ; 






for 


1 


: = 1 to 15 do 






beg 


i n 








N 


ode 


: = 1 Do mS e 1 . s e 1 ec t N 


ode 


( 




7 


r ss / channel / i t em[ ' 


+ 1 


ntToStr ( i ) + ' ]/ti tl e' 


t 


i t 1 


e : = get Chi 1 dNodes 


( No 


de) ; 


L 


I st 


Boxl. 1 t ems, Add( aut h 


o r 


+ 1 : 1 + t i 1 1 e + 






[ 1 + pubDat e + ' / ' ) 







end; 
end; 

The effect of running this program is visible here: 

|[UB(iatej| 

Delphi Haven (CR): Dynamfc arrays — pure reference types, except when they're not [Wed, 9 
Coding with the enemy (Sean): Solving Excels "DBCC TRACEON" error with brute force and I 
Marco's Tech Blog (marcocantu): REST in Delphi: Server Videos [Wed, 9 Dec 2009 12:39:49 
Dr.Bob's Delphi Notes (Bob@eBob42.com): Moving to Delphi 2010, TDBGrid and Title Clicks j 
The VViett Corner fjpluimers): Fiddler replaying requests to the A5P.NET Development Server 
Mick Hodges: Random Thoughts on the Passing Scene #137 [Wed, 9 Dec 2009 02:47:59 +0 
Pawel Giowacki: Direct2D "Advanced Path Geometries" Win? SDK Example Translated to Delp 
About Delphi Programming; Preserve Code Folding When Reopening a Delphi Project [Tue, 8' 
Dee Elling: Installation Options for RAD Studio 2010 [Tue, 8 Dec 2009 01:24:27 +0100] 
TMS Software Biog: Where do you want ... TMS to go in 2010 ? [Mon, 7 Dec 2009 23:00:00 
Malcolm Groves (Malcolm): Hmmm, maybe there's something to this Bing business after all. [ 
Andreano Lanusse (Andreano Lanusse): Delphi Conference Brazil ROCKS!!! [Mon, 7 Dec 2009 
Delphi Haven (CR): Mr Hater gets constructive [Mon, 7 Dec 2009 13:50:13 +0100] 
Source Code Adventures (Cobus Kruger): Lots of Little Bits [Mon, 7 Dec 2009 10:40:00 +010 
Compas Pascal (Lars D): Why there is no app store on Windows [Mon, 7 Dec 2009 09:17:18 
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Of Maps and Locations 

Access to location and map information can be very useful in multiple circum- 
stances, as many applications have to do with addresses. I n the recent years, 
more and more mapping data has been made avail able on the web by many 
large sites, including Google, Yahoo, and Microsoft. 

Google Geocoding Service 

The f i rst servi ce of thi s category I 'm goi ng to use is Googl e's Geocodi ng servi ce, 
which lets you submit an address and retrieve its latitude and longitude: 

Ihttp: / /maps, googl e . com/maps/geo? 
q=[ address] &out put=[format ] &key=[ key] 

You can also type a similar URL in your browser for testing purposes, as you 
can see here showi ng New York coordi nates i n a browser (i n XM L format) : 



Go** 



visw-sourcphttpyVmapi..-. 



C & V!ew-source:hTtp://maps.googlexom/m3ps/geo?q=New%20Yortc,%20JS&output=xm[ ► f> * 



<ianl xnilr.;--"h , c:cp: //earth . google* com/ km!/ 2 ^"xdejpo^ao 
■■CnwiOM'ew York, US</riajne> 
<Scacus> 

<CDdc>200</cocte> 
<zeque3t>geacode</ieque3t> 

<addre33>Mew York, NY r 0SA</addj:e33> 

<Atidre3 3fDetaiis Acc-jracy™" 1" 
xrn \ u - M u rr. : oaau : names : ec : ciq: jesdachema : xAT. :2 . 0 H ><Councry><C:our.TirvM an -eC'Gde>DS</CouiirryHanLeC:adei<Couri»:ryNa 
me>U^</CcunEryt*M«><Aid]iiini3^raciveA^ 

t lveArtaxSubAdminiai: raxiveAreaKaiE.t>N'tw Yark</SubAdru.nxarrat-iveAr«aName><Localicv><LocalL^yNure>Hew 
Yorfc</LGca.lityHaiiLe></LOc«llEy></5ufcA[dirA^ 
<EKter.dedDara> 

<tacton3ox nortti-*40« S494S0C" souch-"4D.57Sei25" easc-"--73 + 'M9e541" weac-*-74 . 2620911" /> 
</£xMndedD4ca> 

<Poincxcocrdin«t3>- , J4 . 005972 9, 4t>. 7112*91, o</coosdlinfl.cesx/Poir.L> 
■C/Plflceniflrk> 



TheGeoLocation example 107 1 've built uses the addresses of the companies of 
theclassicCus t omer . c d s sample database that comes with Delphi. As with 
many similar services, this is free for limited usage (the program has extra calls 
tothesl eep procedure to slow it down and avoid hitting the maximum rate 
per minute), but requires a registration for the specific service on: 
http://code.google.com 



107 A video with the output of both this and the next mapping example is avai lable on You- 
Tube at http:// www.youtube.com/ watch ?v=C_saM KfP2wgand (again) alsoin myblog 
at http:/ / bl og.marcocantu .com/ bl og/ rest_ delphi cli ent_ vi deos.html 
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The demo program requires your devkey to be added to a GeoLocation.ini file 
which must reside in the user's document folder and has the simple structure: 



[google ma p ] 



devkey: 



Resolving Customer Addresses 

The program works i n two steps. First, it looks for unique names of cities/ 
state/ country, by scanning the CI ientDataSet component and filling a string 
list. This code is unrelated to REST, so I 've omitted it from the book 108 . 

The second step is to look up each city on the Google Geocodi ng service, fi I li ng 
an i n- memory CI i entDataSet wi th the resul ti ng i nf ormati on : 



GetTowns 



Geocoding 



Santa Maria, CA, US 
San Jose, CA, US=* 
Lomita, CA, US=* 
Catalina Island, CA, 
Downey, CA, U5=* 
Santa Monica, CA, U 
Venice, FL, US=* 
Winnipeg, Manitoba, 
Runaway Bay, Jamai 
Ocho Rios, Jamaica, 
Milwaukie, OR, US= ! 
Honolulu, HI, US=* 
Maui, HI, US=* 
Tampa, FL, US=* 



Portland, OR, US= 





town 


Latitude 


Longitude 


C 






Lugoff, NC, US 


37.226693 


-77.401371 








Hoover, AL, US 


33.4053867 


-86.8113781 








Pelham, AL, US 


33.2856687 


-86.8099885 








Mobile, AL, US 


30.6943566 


-88.0430541 








Santa Maria, CA, US 


34.9530337 


-120.4357191 








San Jose, CA, US 


37.3393857 


-121.8949555 








Lomita, CA, US 


33.7922392 


-118.3150722 








Catalina Island, CA, US 


33.3878856 


-118.4163103 








Downey, CA, US 


33.9400143 


-118.1325688 








Santa Monica, CA, US 


34.0194543 


-118.4911912 












U 









This ti me rather than aski ng for the XM |_ version of the data, I resorted to a 

simpler CSV format, which the program parses using aT St r i n g L i st object. 

H ere is the actual Geocodi ng code: 

procedure TFor mMap. bt nGeocodi ngCI i c k( Sender : TObject); 
va r 

I : Integer; 

str Response, strl, s t r 2 : string; 
s Li st : TSt r i ngLi st ; 
begi n 

cdsTown. Active : = False; 
cdsTown. Create Da taSet; 
cdsTown. Act i ve : = True; 



108 Don't worry, it is in the book source code. 
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sList : = TStringList. Create; 

for I : = 0 to sListCity. Count - 1 do 

begi n 

Li stBoxl. I teml ndex : = I; 

if Length ( sLi stCi ty. IMa me s [ I ] ) > 2 then 

begi n 

strResponse := I d HTTP 1 . Get ( Tl DUr i . Ur I Encode! 
' ht t p: 1 1 maps . google, c om/ maps I geo? q=' + 
( sLi stCi ty. Na me s [ I ] ) + ' &out put =csv&key=' + 
googl eMapKey) ) ; 
sLi st. Li neBreak := 

sLi st.Text := strResponse; 

s t r 1 : = s Li st [ 2] ; 

s t r 2 : = s Li st [ 3] ; 

cdsTown. AppendRecordf [ sLi stCi t y. Names! I ] , 
StrToFI oat ( st r 1) , StrToFI oat ( st r 2) , 
Length ( s Li s t Ci t y . Va I u e F r o ml ndex [ I ] ) ] ) ; 

Sleep ( 150) ; 

Appl i cati on. Process Me s s a ges ; 
end; 
end; 

s Li st. Free; 



Yahoo Maps 

As a further step, we can try to access to the actual map correspondi ng to an 
address. I f Google M aps provide countless features, they are meant to be hos- 
ted on web sites not on client applications 109 . 

The new example, cal led YahooM aps uses Yahoo M ap API to get an actual map 
and show it in an I mage control . Information about this REST API and thelink 
to obtain a free Yahoo Application I D are avail able at: 

http: / /devel oper. yahoo, com/ maps/ 

Again, to run the programs you'll have to obtain this I D and store in a specific 
INI f i I e i n the "user documents" fol der cal I ed YahooM aps. i n i . The map i s 
retri eved i n two steps: a f i rst H TTP cal I passes the address and recei ves the 
URL of the map i mage, which is retrieved usi ng a second HTTP cal I . Agai n, you 
could simulate the two steps in a web browser, for debugging purposes. 

While the program uses the same database and intermediate StringList of the 
previous example, it also has a button that it uses to display the map or a hard- 
coded city (San J ose, California), using the fol lowing method: 



109 Although I do have an example of hosting a Google Map in a client program, its architec- 
ture and code are quite complex and the example won't fit in this chapter. 
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const 

BaseUrl = 'http://api.local.yahoo.com/MapsService/Vl/'; 
procedure TFor mMap. But t onlCI i ck( Sender : TObject); 
va r 

s t r Re s u I t : string; 
me mS t r : t F i I e 5 1 r e a m; 
begi n 

strResult := I d HTTP 1 . Ge t ( Ba s e Ur I + 'maplmage?' + 

' appi d=' + yahooAppid + 

' &ci t y=SanJ ose, Cal i f or ni a') ; 
XML Do c u me n 1 1 . Ac t i ve := False; 
XMLDocument 1. XML. Text := strResult; 
XML Do c u me n 1 1 . Ac 1 1 ve := True; 

strResult := XML Doc u me n 1 1 . Do c u me n t E I e me n t . No de Va I u e ; 

XML Do c u me n 1 1 . Ac 1 1 ve := False; 

// now let's get the referred i mage 

memStr: = TFIIeStream. Create ( ' t emp, png' , fmCreate); 

I dHtt pi. Get ( str Resul t , memStr); 

memSt r . Free; 

// load the i mage 

I ma gel. PI ct ure. LoadFromFi I e ( ' temp, png' ) ; 
end; 

The first HTTP Get request provides the actual query and returns an XM L doc- 
ument with theURL of the i mage of the actual map, which lookslike: 
<Res ul t > 

htt p: / / gws. ma ps.yahoo.com/ ma pi ma ge? MA PDATA=[ 
&a mp ; c I t y pe =o n n e t wo r k &a mp ; . I n 1 1 =us &a mp ; appi d 
&a mp ; oper=& _proxy=ydn, xml 
</ Resul t > 

That's why the program can extract the val ue of the only node with the code: 
| XMLDocumentl. Document El ement. NodeVal ue 
Finally, the image is saved to a file and loaded into an I mage control : 



. . . ] &a mp; mvt =m 
=[...] 



jg YahaaMap 



L±i=L 



BE 

Wacwhu. HI, US-* 
Kafcja-Kww, m, US-" 
Kitchener , Ontario., Canada-" 
Marathon, FL, US--* 
Grtatf, Oft, US-" 
Sarasota, H., US = - 
Mftfjrd, Jamaica, West Inctes 
St Simons Isle, GA, US-* 
largo, FL, US-* 
Eugene, or, us-' 
Vancouver, BC, Canada- 1 
Ayxre Metttiasos, Corfijj Gr«o 

Houston, TX, U5-* 
LugofTpNC.US^- 
Hoaver, AL, US-* 
P-efram, AL,US-* 
Wobte, AL, US-* 
Santa Maria, CA. UE-* 
San Jox, CA> US-" 
lamia, CA.uS-" 
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Beside the map of this specific city, the program can also fetch those of the 
C u s t o me r . c d s database of the previous example. 

Google Translate API 

Another simple and interesting example of a REST API provided by Google is 
their translation service, called Google Translate REST API . The documenta- 
tion is at: 

http: / /code, googl e, com/api s/aj axl anguage/documentati on/ 

In this case there is no need for a signup key (and an INI file), but only provide 
a referrer site (although everythi ng seems to work even without that i nforma- 
tion). You can ask for a translation in your Web Browser by entering an URL 
like: 

htt p: / / a j ax. googl eapi s, com/aj ax/servi ces/l anguage/ 

t r a n s I a t e ? v =1 . 0 &q =Wh a t %2 0 a %2 0 n i c e %2 0 d a y & I a n g p a i r =e n | d e 

j Q httpi//aj«K.gw?gleapihCQ-, * 

4- C 6 fiiipy.'ajaxgo^leapiMom/ajax/semces/language/tra^ ► Q» 

(■taaf-anaeData-i i "tsanalatedTeM t" i "Has Vis els ae*a*e]? Tao"]. "raspe-fcaeDe-raila - s null, ■taapanaaseaeua- s 200) 



Theoutput of this call is visible above (I have also listed thej SON resultfor 
readability): 

{ 

"responseData": 
{ 

"transl atedText": "Was fur ein schdner Tag" 

}, 

" r e s p o n s e De t a i I s " : null, 
"responseStatus": 2 0 0 

} 

This example takes one step further compared to previous demos. Rather than 
making the HTTP request, it uses a specific custom VCL component, invoked 
with a class method (so you don't need to pi ace the component on a form, even 
if you could). This support component makes the API very easy to use, and 
encapsulates the HTTP call completely. 
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A Translation Component 

The class of the component stores information about the request and encapsu- 
lates an internal HTTP client component, as you can see in its declaration: 
type 

TBabel Googl eRest = class (TComponent) 
protected 

Httpl: TldHttp; 

FFromLang: string; 

FToLang: string; 

FActivelnForm: Boolean; 

procedure Set FromLang) const Value: string); 
procedure SetToLang( const Value: string); 
public 

function DoTransi ate (strln: string): string; virtual; 
constructor Cr ea t e ( AOwne r : TComponent); override; 
class function Translate ( 

strln, langln, langOut: string): string; 
publ i shed 

property FromLang: string read FFromLang write Set FromLang; 
property ToLang: string read FToLang write SetToLang; 
end; 

The actual processing (the REST call) is performed in theDoTr a ns I ate func- 
tion, which uses the input and output languages set for the class: 

function TBabel Googl eRest. DoTransi ate(strl n: string): string; 
va r 

s t r Ur I , s t r Re s u I t : string; 
nPosA, nPos B: Integer; 
begi n 

s t r U r I : = F o r ma t ( 

' ht t p: 1 1 a] ax. googl eapi s . com/ajax/services/language/' + 

' f r a n s I a t e 1 v =1 . 0 &q =%s &l a n g p a i r =%s ' , 

[TldUri. Para ms Encode (strln), 

FFromLang + 1 %7C + FToLang]); // format hates %7 
st r Resul t : = Ht t p 1 . Ge t ( s t r Ur I ) ; 
Result := Resul tFromJ SONDi rect (strResult); 
end; 

The result of the request to the given URL is in J SON format (as this is con- 
sidered as a J avaScri pt API by Google) . As I origi nal ly wrote this code for a past 
version of Delphi, the program parsed thej SON stri ng to extract the actual res- 
ult usi ng di rect stri ng mani pul ation: 

functi on TBabel Googl eRest. Resul tFromJ SONDi rect( 

const strjson: string): string; 
va r 

nPosA, nPos B: Integer; 
begi n 

nPosA := Pos ( ' " t r a ns I a t e dTex t " : ' , strjson); 
if nPos A = 0 then 
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begi n 

nPosA := Pos ( ' " r es pons eDet ai I s " : ' , strjson); 

nPosA : = nPosA + Length ('"response Details":'); 
end 
else 

nPosA := nPosA + Length ( ' " t r ans I at edText " : ' ) ; 

nPosA := PosEx ('"', strjson, nPosA) + 1; // opening " 
nPosB := PosEx ('"', strjson, nPosA) - 1; // end " 
Result := Copy (strjson, nPosA, nPosB - nPosA + 1); 
end; 

As I moved the code to Delphi 2010, 1 tried using the using the new Delphi 

J SON support to accomplish the same, in a cleaner way. This is implemented in 

the alternatively s u I t F r o mj SON function, which actually highlights problems 

of thenativej SON parsing. First, you have to remove white spaces in thej SON 

representation (but only outside of the quoted strings), or the parser will fail™. 

The string cleaning up operation is performed by a Re move Whi t e s function: 

function RemoveWhltesfconst strl: string): string; 
va r 

c h : char; 

i nQuot es : Bool ean; 
begi n 

Result : = 1 1 ; 
i nQuot es : = False; 
for ch in strl do 
begi n 

if c h = 1 " 1 then 

i nQuot es : = not i nQuot es ; 
if I nQuot es or ( c h <> 1 1 ) then 
Result : = Result + c h; 

end; 
end; 

After this step the program gets the value of the first pair (responseData) of the 

J SON object, which is in turn an object, and read the string value of the first 

pair (translatedText) of this sub-object: 

fundi on TBabel Googl eRest. Resul tFromJ S ON ( 

const strjson: string): string; 
va r 

s t r T e mp : string; 

jObject, j ResponseData: TJSONObject; 
begi n 

// parse J SON using Delphi 2010 support 
strTemp : = RemoveWhites (strjson); 



110 The inability of parsing J SON with spaces is a bug and I have reported it on Quality 
Central with number 80262. Thej SON RFC, in fact, specifically accounts for any white 
space within the J SON symbols. Seems this is going to be solved as part of a hotfix, 
which isstill not avail able at the time I'm writing. 
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jObject := TJ SONObj ect. Parse] SONVal u e ( 

TEncodi ng. ASCI I . Get By t es ( s t r Temp) , 0) as TJSONObject; 
try 

if not As s i g n e d ( j Obj ec t ) then 
Exit ('Error parsing ' + strTemp); 

// read value of first pair of obj ect , as subobj ect 

j ResponseData := j Obj ect. Get(0).J sonVal ue as TJSONObject; 

// get value of only element of responseData 
Result := j Re s p o n s e Da t a . Ge t ( 0 ) . J s o n Va I ue . Va I ue ; 

finally 

j Obj ect . Free; 

end; 
end; 

At the ti me wri ti ng, th i s code f ai I s m for any U n i code stri ng, wh i ch are a I arge 
majority of those managed in the demo program, considering the number of 
non-Latin languages Google Translation supports. 

To perform the translation, the actual Do T r a ns I ate method can be i nvoked 

di rectly after creati ng an i nstance of the object and setti ng its properties, it can 

becalled using theTr a n s I ate class method. This function creates a temporary 

object, sets its properties, and callstheDoTr a ns I ate function on it: 

class function T B a be I Googl e Re s t . Tr a ns I a t e ( c ons t 

strln, langln, langOut: string): string; 
va r 

bg: TBabel Googl eRest ; 
begi n 

bg : = self.Create(nil); 
try 

bg. FromLang : = langin; 

bg.ToLang := langout; 

Result := bg. DoTransi ate(strl n); 
finally 

bg, Free; 
end; 
end; 

The main form of the demo program has a list box filled with all supported lan- 
guages. The demo translates from English, but you can set it up in the opposite 
direction as well. I n theory, any two language token combination works, in 
practice not always. Once you ask for a translation, the result is added to a log. 



Ill The Parse] SONVal ue method expects an array of bytes ( representi ng characters) as 
parameter and will return an empty object in case of a Unicode string in input (whatever 
its content). If you convert theinput to ANSI , any high character will not convert. Ifyou 
convert it to UTF8, it will treat individual bytes as characters, which will not work, 
either. Again, it looks I ike this is going to be solved by a Delphi 2010 hotfix. 
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H ere I 've appl i ed the cal I to the f i rst grou p of I anguages ( i n al phabeti c order) , 
using direct J SON result string processing and notDelphi'sJ SON parser: 

H TranslateForm I 1=1 I B I^Ml ' I 



Welcome to San Jose German Italian Pick 







ar=Arabic 




flo6pe aoom b CaH Xoce 




bg=Bulgarian 




Benvingut a Sant Josep 




ca=Catalan 








zh-CN=Chinese simpl. 








zh-TW=Chinese trad, 




Dobrodosli u San Jose 




hr=Croatian 




Vitejte na San Jose 




cs=Czech 




Velkommen til San Jose 




da=Danish 




Welcome to San Jose 




nl=Dutch 




Maligayang pagdating sa San Jose 




ti=Filipino 




Welcome to San Jose 




fi=Finnish 




Bienvenue a San Jose 




fr=French 




Willkornrnen in San Jose 




de=German 




KqAujc; rjASkTTE oto San Jose 




el=Greek 




nnn id"? a 4 *an nana 




iw=Hebrew 








hi=Hindi 




Selamat datang ke San Jose 




id Indonesian 




Benvenuti a San Jose 




fMtaSan 





Building a REST Server 



Now that we have spent a considerable amount of ti me looking at a few REST 
client applications written in Delphi, facing different permission requests and 
usi ng different data type formats, we are ready to start del vi ng i nto the second 
part of this chapter, focused on writing REST servers in Delphi 2010. 

J ust as building a REST client is more straightforward and requires less sup- 
port from developer tools than building a SOAP client, the same can be said for 
the server. It is true that a SOAP server is a web server with an extra compon- 
ent for mappi ng requests to classes, but a REST server can be a plai n web 
server extension with little additional code. 

In this section I'll introduce the development of REST servers using a simple 
application built on top of the plain Web Broker architecture, something you 
could have done si nee Delphi 4. In the remaining part of the chapter, I'll focus 
on the development of REST servers based on the specific DataSnap extensions 
available in Delphi 2010. 
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To build the Resti project I created a standard webserver usi ng the Web App 

Debugger technology, al ready covered and used in the last chapter for some of 

the HTTP DataSnap applications. The web program has four actions, a sample 

Echo operation similar to the predefined DataSnap ones, and three database 

oriented requests. Each of the actions of the web modules has a corresponding 

On Ac t i on event handler: 

Actions = < 
item 

Default = True 

Name = ' act i on Echo' 

Pat hi nf o = 1 / Echo 1 

On Action = acti onEcho Action 
end 
item 

Name = 'actionCustomers' 

P a t h I nf o = ' / Cust omer s ' 

OnAction = a c t i o n Cu s t o me r s Ac t i o n 
end 
item 

Name = ' act i on Cust Dat a' 

Pat hi nf o = 7 Cust Data' 

OnAction = a c t i o n Cu s t Da t a Ac t i o n 
end 
item 

Name = 'actionCustomer' 
Pathlnfo = ' / Cust omer / * ' 
OnAction = acti onCustomerActi on 
end> 



An Echo Action 



Theacti on Echo operation is a sample action mi mi eking the sample operation 
of DataSnap servers (i ncl udi ng the REST ones, as we'l I see) . This operation has 
a parameter, passed with the i n parameter name, and the response is sent back 
using a simple XML fragment and the corresponding HTTP response type: 

procedure TWebModul e3. acti onEchoActi on( Sender: TObject; 

Request: TWebRequest; Response: TWe b Re s p o n s e ; 

var Handl ed: Bool ean) ; 
va r 

strlnput: string; 
begi n 

strlnput := Req ue s t . Que r y F i e I d s . Va I u es ['in']; 
if strlnput = ' ' then 

strlnput : = ' Not hi ng to echo' ; 
strlnput := strlnput + + Copy ( 

strlnput, Length (strlnput) - 4, 5); 
Res po ns e . Co n t e n t := '<result>' + strlnput + ' </ r es ul t >' ; 
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Response. ContentType := ' t ext / xml ' ; 
end; 

How can you call this operation? From a web browser, after we run the pro- 
gram and start the Web App Debugger, we can use the foil owing URL: 

ht t p: / / I oca I host : 8081/ Rest 1. r est 1? i n =h e I I o %2 0 wo r I d 
The result will look like: 

<result>hello worl d. . . worl d</resul t> 

Nothing extraordinary but relatively simple. Wecan putthesameURL in a 
Delphi client application (the RestlClient example), passing the text of an edit 
box as parameter and encoding it: 
const 

BaseUrl = 'http: //local host: 8081/Restl.restl'; 

procedure TForm3. btnEchoCI i ck(Sender: T Object); 
va r 

strlnput, strResult: string; 
begi n 

strlnput := TldURI. Para ms Encode ( edEcho. Text ) ; 
strResult := I d HTTP 1 . Ge t ( Ba s e Ur I + '?//?=' + strlnput); 
I b I Echo. Caption : = DataFromTopTag (strResult); 
end; 

The Da t aFromTopTag support fundi on (not listed here) removes the top and 
any XM L tags from the response. 



Returning the XML Data of a ClientDataSet 

The second action, act i onCust Dat a, is the simplest to implement, on both the 
server and cl ient side. Al I it does is return the enti re data content of a Client- 
DataSet component, using itsXML representation. The server simply returns 
that XML: 

procedure TWebModul e 3 . acti onCust Dat aAct i on( 

Sender: TObject; Request: TWebRequest; 

Response: TWebResponse; var Handled: Boolean); 
begi n 

Res po ns e . Co n t e n t := c ds Cu s t o me r s . XML Da t a ; 
Response. ContentType := ' f ext / xml ' ; 
end; 

Using the corresponding URL you can see the enti re XML data of the Client- 
DataSet in a browser, like in thefollowing page: 
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Pi vierw-source:http://localh... ■< \ \ Q '. 



\®\m&m\ 



#" -> O & view-source:http://localhost:80Sl/Restl.restl/custdata 



WI DTH= " 3 0 " / X FIE LD 
WIDTH-"30"/xFIELD 
WIDTH="15"/XFIELD 
WIDTH="20"/XFIELD 
a t t rname= " Count r y " 



<DATAPACKEr Ver3_or.= "2 . 0"XMETADATAXFIELDSXFIELD att.rr.air.e="Cu3CNo " 
f ieldtype="r8 "/XFIELD attrname="Comp-any " f ieldtype="string" 
WIDTH-"30"/xFIELD attrnarr.e="Addrl " f ieldtype="string" 
attrr:arr.e="Addr2 " f ieldtype= rr stririg" 
attrr;arr.e="City " fieldtype= "string" 
attrnair.e=" State" f ieldtype="string" 

attrname="Zip" f ieldtype="string" WIDTH="10"/XFIELD 
f ieldtype="string" WIDTH="20 "/XFIELD 
attrname="Phone" f ieldtype="string" WIDTH="15"/XFIELD attrname="FAX" 
fieldtype="string" WIDTH="15 "/XFIELD attrname="TaxRate " 
fieldtype="r8 "/XFIELD attrnaiue="Contact" f ieldtvpe="string" 
WIDTH="20"/XFIELD atti:iiame="LastInvoiceDate" 
f i e 1 dt yp e= " da t eT ime " / X / FIELDS X P ARAMS DE FADLT_ORDER= " 1 " 
PRIMARY_KEY="1" LCID="1033"/X/METADATAXROWDATAXROW CustNo="1221" 
Corrpar.y="Kauai Dive Shoppe" Addrl="4-976 Siigarloaf Hwy" Addr2="Suite 
103" City="Kapaa Kauai" State="HI" Zip="94766-1234." Countiy="OS" 
Phone="808-555-Q269" FAX="808-555-0278" TaxRate="8 . 5 " Contact="Erica 
Norman" LastInvoiceDate="1995Q2Q2T01 : 05 : 03000 "/XROW CustHo="1231™ 
Corr.pa:~y="UniscQ rr AddrI= rr P0 Box Z-547" City="Fi:eepoi:t" Co^r.try= rl 3ahaic,as rl ' 



A Delphi client application can easily access that data: 

procedure TForm3. btnCDSCI i ck( Sender: TObject); 
begi n 

Client Dat aSet 1. CI os e; 

CI i ent Dat aSet 1. XMLDat a := I d HTTP 1 . Get ( BaseUr I + ' / c us t d at a 1 ) ; 
CI i ent Dat aSet 1. Open; 
end; 

In this client application the ClientDataSet is connected with aDBGrid, so you 
can immediately see the server side database in the client program, passed 
through the REST call. You can seethe result of the first two operations in the 
top part of the form of the RestlCI ient demo: 

jg RestlClient I. ■=■ 1 B I^MT 



hello world btnEcho hello world.,, world 





CustNo Company 


Addrl 








1221 Kauai Dive Shoppe 


4-976 Sugarloaf Hwy 








1231 Unisco 


PO Box Z-547 








1351 Sight Diver 


1 Neptune Lane 








1354 Cayman Divers World Unlimited 


PO Box 541 










i 


□ 




► 





Implementing a client for this data access call in J avaScript or in a non-Delphi 
client might not be trivial, because the XML of the ClientDataSet component is 
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quite specific. Also, returni ng the enti re data structure for a large data set 
might be excessive in terms of bandwidth. A more REST-oriented alternative 
might be to return a list of available records and then individual records with 
the data. This implies more processing both on the server and the client, but it 
is certainly worth exploring. 



Returning a List of Customers 

The server action returning a list is called with the customers URL. In its server 
code, the application scans the data set and returns an XML structure with the 
company name and the customer I D for each customer record. With the URL: 

h 1 1 p : / / I o c a I host: 8081/ Rest 1. restl/customers 
You'll see an XML result like: 

<c us t omer s > 
<c u s t o me r > 
<i d > 1 2 2 1</ i d> 

<Company>Kauai Dive S h o p p e </ Company> 
</ c us t o me r > 
<c u s t o me r > 

<i d>1231</ i d> 

<Company>Uni sco</Company> 
</ c us t o me r > 



ThisXML code is generated using as a helper theTTr i vi al Xml Wr i t er class as 
a helper that I covered in Chapter 3, in the section "TheTrivial XML Writer 
Class" under the heading "XML Streaming". This is a class that let's you write 
to an XML stream or string, using theTText Wr i ter interface introduced in 
Delphi 2009. It keeps track of theXML nodes you open so it can close them in 
the reverse order, without specifyi ng which tag you are closi ng. 

I n this specific case, the program uses a T S t r i n g Wr i t e r , as we are returni ng a 
stri ng. The server code scans the data set component from the f i rst to the I ast 
record and outputs the customer I D and company name: 

procedure TWebModul e 3 . acti onCustomersActi on( 

Sender: TObject; Request: TWebRequest; 

Response: TWebResponse; var Handled: Boolean); 
va r 

s w: TSt r I ngWr I t er ; 
x ml w: T T r i v i a I X ml Wr iter; 
begi n 

sw : = TStrlngWr Iter. Create; 
try 



Marco Cantu, Delphi 2010 Handbook 



Chapter 8: REST Web Services - 279 



xmlw : = TTrivialX ml Writer. Create (sw); 
try 

x ml w. Wr I teStartEl e me n t ( ' c us t omer s ' ) ; 
cdsCustomers. F i r s t ; 
while not cdsCustomers. Eof do 
begi n 

x ml w. Wr I teStartEl e me n t ( ' c us t o me r ' ) ; 
x ml w. Wr I t e 5 1 a r t E I e me n t ( ' / d ' ) ; 

x ml w. Wr i t eS t r I n g ( c ds Cu s t o me r s [ ' Cust No'\ ) ; 
xml w. Wr I t e End El ement ; 
x ml w. Wr I teStartEl e me n t ( 'Company' ) ; 

x ml w. Wr I t eS t r I n g ( c ds Cu s t o me r s [ 'company' ] ) ; 
xml w. Wr I t e End El ement ; 
xml w. Wr I t e End El ement ; 
cdsCustomers. Next; 
end; 

xml w, Wr I t e End El ement ; 
finally 

x ml w. Free; 
end; 

Res po ns e . Co n t e n t := sw.ToStrlng; 

Response. ContentType := 1 text /xml ' ; 
finally 

s w. Free; 
end; 
end; 

The last action returns data for a specific customer, an individual record. The 
Pat hi nf o for this last action is different from the others. Rather than indicat- 
ing aspecific URL, in fact, it uses the notation '/Customer/*' to indicate any 
URL starting with that portion. The standard approach with REST, in fact isto 
use the U RL path (and not its optional parameters) to refer to a given resource, 
in this case a customer. Foil owing this style, we can use the foil owing URL to 
refer to the fi rst record: 

ht t p: // I oca I host : 8 0 8 1 / Res 1 1. rest 1/ cust omer / 122 1 
This is the corresponding response in a web browser: 







■ : I □ , @ |— £3-4 




/□ 


view-50urce:http://localh... ■ N^Q^ 










C # wew-source:http:.//localhost:3081/Restl.restl/Customer/1221 ► 




1 


<custorf.er><C^3tNo>12 2 K/Cu3tNoxCcrr.par.y> Kauai Dive S'rjoppe< / Ccrrpar.y><Addrl>4- 
976 Sugar-loaf Hwy</AddrlxAddr2>Suite 103</Addr2XCity>Kapaa 
Rauai</CityxState>EI</StatexZip>9476 6- 

1234</ZipxCountiy>US</CQuntryx Phone >808-SS5-0269</PiiQ!iexFAX>808-SS5- 
0278</FAXXTaxRate>8 . 5</TaxRatexContact>Erica 
Nornari</ContactxLa3tInvoiceDate>2/2/199S 1:05:03 
AM</LastInvoiceDatex/cu3torr.er> 
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All we have to do in our last action (acti onCustomer) is to extract the last part 
of the URL and use it as a parameter: 
const 

u r I Acti on: AnsiString = ' / Res 1 1 . r es t II Cus t o me r I ' ; 
begi n 

strCustld := Copy ( Reques t . Pat hi nf o, 
Length ( u r I Acti on) + 1, Ma xl nt ) ; 

NoticethatthePat hi nfo property of the R e q u e s t is an AnsiString, so we have 
to use the same stri ng type of the constant part we want to remove from the 
path we receive" 2 . 

Now that we have the customer id, we can write out each field of the given 

record, agai n usi ng a T T r i v i a I X ml Wr i t e r support object: 

x ml w. Wr i t eS t a r t E I e me n t ( ' c us t omer ' ) ; 
cdsCusto me rs. Locate) 'custno', strCustld, []); 
for I := 0 to cdsCusto me rs.FieldCount - 1 do 
begi n 

xml w. Wr i teStartEl ementfcdsCustomers. Fl el d s [ I ]. Fl el dName); 
xml w. Wr i teStrl ng( cdsCusto me rs. Fl el d s [ I ]. AsStrl ng); 
xml w. Wr I t e End El ement ; 
end; 

xml w. Wr I t e End El ement ; 

Now that we have seen how the server can return the list of customers and indi- 
vidual customer records, let's focus on the corresponding Delphi client 
application. This time there is nothing specific to Delphi, so you could use other 
development tools for the client. 

The code for processing the list is rather complex only because I 'm parsing the 
resulting XML directly, rather than using an XMLDocument component and 
DOM orXPath ( as i n the RSS Feeds client demo, for example). I populatea list 
boxfrom the resulting data with thedisplayed string having theid=name 
format: 

procedure TF or m3 . b t nCus t L I s t CI I c k ( Sende r : TObject); 
va r 

strLi stCust, strld, strName: string; 
nPos : Integer; 
nlnit, n E n d : Integer; 
begi n 

Li stCust. CI ear; 

strLi stCust : = I d HTTP 1 . Ge t ( Ba s e Ur I + 1 / c us t o me r s 1 ) ; 



112 UsingANSI strings for URL will not work properlywith the new breed of "Non-Latin" 
URLs, recently introduced by ICANN (http://www.icann.org/ en/ announcements/ an- 
nouncement- 30oct09-en.ht). As an example of a Chinese language URL you can use 
http://#!l : ?-.;IlT^/1f 35 (or the easier-to-type version, http://bit.ly/d2z7pp). 
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nPos := Pos ( ' <c u s t o me r ><i d >' , strLi stCust); 
wh i I e nPos > 0 do 
begi n 

nlnit := nPos + 14; // Length <c u s t o me r ><i d > 
n E n d : = PosEx ('</id>', strLi stCust, nPos); 
strld := Copy (strListCust, nlnit, n E n d - nlnit); 
nPos := PosEx ( ' <company>' , strListCust, n E n d ) ; 
nlnit : = nPos + Length ( ' <c ompa ny >' ') ; 
nEnd : = PosEx (' </ 'company ■>' , strListCust, nPos); 
strName : = Copy (strListCust, nlnit, nEnd - nlnit); 
Li stCust. I terns. Add (strld + ' =' + strName); 
nPos := PosEx ( ' <c u s t o me r ><i d >' , strListCust, nEnd); 
end; 
end; 

When you have the list of the customers, you can use the ID of the selected item 

to prepare the proper URL to grab its detailed data (which in this case is simply 

displayed as is on a Memo: 

procedure TForm3. Li stCustDbl CI i ck(Sender: TObject); 
va r 

strCust: string; 
begi n 

strCust : = Li stCust. I terns. Mames [ Li stCust. I teml ndex] ; 
MemoCust. Lines. Text : = 

I dHTTPl. Get ( BaseUrl + '/customer/' + strCust); 

end; 

H ere i s the bottom part of the si mpl e user i nterf ace of the RestlCI i ent appl i ca- 
ti on showi ng the I i st box wi th the customers and the raw X M L data of the 
selected one: 



1221=Kauai Dive Shoppe 

1231=Unisco 

135 l=Sight Diver 

1354=Cayman Divers World Unlimited 
1356=Tom Sawyer Diving Centre 
tfc::!»li!il|jTl.!JJilBT~ 

1384=VIP Divers Club 
1510=Ocean Paradise 
1513=Fantastique Aquatics 



1CG1-M=i-r 



IJ 



<ojstomer > <CustNo > 1 380 </Cust 
NoXCompany>Blue jack Aqua 
Center </Company xAddr 1 > 23 - 
738 Paddington 
Lane</Addr l><Addr2>Suite 
3 10</Addr2><City>Waipahu</Cit 
y><State>HI</State><Zip>99776 
</Zip > <Country >US</Country >< 
Phone>401-609- 



btnCustList 



Building a DataSnap REST Server 



As we have seen in the previous section, you can build REST servers in Delphi 
usi ng the WebBroker architecture. A second alternative is the use of the I dHT- 
TPServer component. Further options are provided by third- party solutions. All 
of these options were already avail able in past versions of Delphi and arecer- 
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tainly still possible today. The focus of the rather long remaining part of the 
chapter, though, is the new REST support which is part of the DataSnap archi- 
tecture in Delphi 2010. 

To build a first simple DataSnap REST server 113 in Delphi 2010 we can use the 
DataSnap Wizard, as we did in the last chapter for building other DataSnap 
servers. H owever, if you want to host your REST server as a web server, picki ng 
the DataSnap WebBroker Application will probably be your best choice. The 
DataSnap WebBroker architecture, i n fact, lets you have more control over the 
HTTP requests coming in and lets you integrate your REST data within your 
WebBroker server. 

As soon as you pick HTTP support in a DataSnap application or select a Data- 
Snap WebBroker server, the resulting application will automatically include 
support for REST. 

We have al ready seen i n the last chapters which units are generated by the 
DataSnap WebBroker Wizard, here I 'm only underlying a few specific elements 
worth considering for a REST server. 

The web module generated by the Wizard is the core element of the WebBroker 
architecture. It can define multiple actions and has pre-processing and post- 
processing events for any HTTP request. The Wizard adds a DSHTTPWebDis- 
patcher component to the web module: 

object DSHTTPWebDi spatcherl: TDSHTTPWebDi s pat c her 

RESTContext = 'rest' 

Server = DSServerl 

WebDi spatch. MethodType = mtAny 

We bDi spatch. Pathl nfo = 'datasnap*' 
end 

This component intercepts any request with a URL starting with 'datasnap', 
which are passed to the HTTP support of DataSnap. For requests starting with 
'datasnap' and i ndicati ng a 'rest' path, the processi ng wi II be diverted to the 
built-in REST engine 114 . In other words, the requests with a 'datasnap/ rest' 
path are considered as REST requests. 



113 A video of the development of this REST server application step-by-step is available on 
YouTube at http://www.youtube.com/ watch?v=TxFB8mjiGr8 and in myblogat 
http:// blog.marcocantu.com/ blog/ rest_ delphi_ server_ videos.html . As for the past 
videos mentioned in this chapter, I recorded this video for the Embarcadero white paper. 

114 Notice that while you can change the 'rest' element of the path with anything you like, 
you cannot remove it altogether. At the opposite, it seems i mpossi ble to change the 
'datasnap' portion. If you try to do so, you'll see an error when you try to connect. 
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The web module provides also a default HTTP response for any other action, 
si mply returning some bare- bones HTM L: 

procedure TWebModul e 2 . We b Mo d u I e 2 D e f a u I tHandl erActi on( 

Sender: TObject; Request: TWebRequest; 

Response: TWebResponse; var Handled: Boolean); 
begi n 

Res po ns e . Co n t e n t := ' <ht ml xheadi ng/ ><body>' + 
'Data Snap Ser ver </ bodyx/ ht ml >' ; 

end; 

This action is configured at design-time as: 

Actions = < 
item 

Default = T r u e 

Name = ' Def aul t Handl er ' 

Pat hi nf o = 7 ' 

OnActlon = WebModul e2Defaul tHandl erActi on 
e n d > 

At the core of the application, like any DataSnap REST application, thereisthe 
server class, the class surfacing methods to be called remotely via REST. Notice 
that REST support is i n fact focused only on server methods, and doesn't let 
you access the I A p p S e r v e r i nterface exposed by the Dataset Provider compon- 
ents. 

The skel eton cl ass that gets generated i s very si mpl e, and depends on the fact 
that I asked for sample methods i n the wizard. H ere is the code, once agai n: 
type 

TSe r v e r Me t h od s 1 = c I a s s ( TDS S e r ve r Mod u I e ) 
pr i vat e 

{ Pri vat e dec I arati ons } 
public 

function Ec ho St r i ng ( Va I ue : string): string; 
end; 

TheEchoStri ng method by default simply returns the passed parameter you 

are passing, but I've updated it slightly to repeat the tail of the string, asin a 

real "echo": 

functi on TServerMethodsl. EchoStri ng( 

Value: string): string; 
begi n 

Result : = Val ue + ' . . . ' + 

Copy (Value, 2, maxint) + + 

Copy ( Val ue, Length ( Val ue) - 1, 2) ; 

end; 
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Accessing the REST Server with a Browser 

We can test this server to see if it works. After compi I i ng and runni ng the pro- 
gram, remember to run the Web App Debugger (available in Del phi's Tools 
menu), and start it using the corresponding button. The Web App Debugger 
runs on a specific port, by default 8081, so the URL will start with: 

http: //local host: 8081/ 
Next in theURL comes the application name and theWeb App Debugger class 
name(which in this case are identical), separated byaperiod: 

FI rstSI mpl eRestServer. FI rstSi mp I eRestServer 

I f you open the combi ned U RL i n a Web browser you can check if the Web App 
Debugger and the specific server are running. You should see something like: 



f 




<>^' I - j [H] \ m EbJ 




view-50urcEhttp://lotalri... 0 




«- 


C & - ew-5ource:hnp://localhast308iyFifstSifTipteRestServer.FirstStm 


pleRestServer ► D T T 


t 


<r.z7r.L><r.*e.zL7.c '><'czi-_->2eL-zs.Sr.a.z Server<. , 't-cd^><.-'?i^[rJL> 



This is the useless HTM L returned by the program for the standard action. The 
next step isto use the specific URL for the only request our REST server can 
perform, calling theE c ho St ring method of theTSe r ver Met hods 1 class using 
the 'rest' support of our 'datasnap' server. TheURL is automatically combined 
by adding the REST server prefix (/datasnap/rest, by default), the class 
name, the method name, and the method parameters: 
/ datasnap/ rest / T5erverMet hodsl / EchoSt r i ng/hel I o %2 0 wo r I d 

I n the URL the%20 isjust a replacement for a space, but you can actually type 

a space in your browser. Now the complete URL becomes: 

http: //I ocal host: 8 0 8 1 / F i rstSI mpl eRestServer. FI rstSi mpl eRestServer/ 
datasnap/ rest/TServerMethodsl/ EchoSt ri ng/hel I o %2 0 wo r I d 

If you type it in a browser, you'll see the foil owing J SON response: 









/D 


view-sourcchttpi/ylDcalh... \ O 






-> 0 & 'StSimpleRestServef/datasnap/rest/TServerMet 


lodsl/EchoStrf no/he llo%20wortd| ► f"* 


,— 


{"result": ['hello world. . .ello world. . .Id") ) 
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The response you get when calling a server method is invariably aj SON object 
with a single pair called "result". The value of this pair is always an array 135 , 
with the actual value returned by the method (a simple data type, an object, an 
actual array). 

N oti ce that whi I e doi ng th i s test we can use the Web App Debugger for f i gu ri ng 

out the actual HTTP requests and responses bei ng transferred. The page above 

is originated by a browser request: 

GET / F i rstSi mpl eRestServer. Fi rstSi mpl eRestServer/ 

dat as na p/ r es t / TSer ver Met hods 1/ Ec ho St r i ng / hel I o %2 0 wo r I d HTTP / 1 . 1 
Host : I ocal host : 8081 
Connection: keep- a I i v e 

User-Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; 

en-US) Appl eWebKi t / 5 3 2. 0 ( KHTML, like Gecko) 

Chrome/ 3, 0. 1 9 5. 27 Safari / 5 3 2. 0 
Accept: appl i cati on/xml , appl i cati on/ xhtml +xml , text/html ; 

q=0. 9, text/pi ai n; q = 0. 8, i mage/png,*/*;q=0. 5 
Accept- Encodi ng: gzip, deflate, sdch 
Cookie: LastProgl D= 

Fi rstSi mpl eRestServer. Fi rstSi mpl eRestServer 
Accept- Language: en- US, en; q=0. 8 
Accept - Char set : I SO- 885 9- 1, u t f - 8; q =0 . 7 , * ; q =0 . 3 

This request produces the following complete HTTP response: 

HTTP/ 1.1 200 200 OK 
Connection: close 
Content-Type: TEXT/HTML 
Cont ent - Lengt h: 44 

{" r e s u I t " : [ " hel I o wor I d. . . el I o wo r I d . . . I d " ] } 

As I mentioned earlier, the easy access to this low-level information can bea 
bi g bon us when debuggi ng H TTP appl i cati ons. 



Returning Multiple Results 

As mentioned earlier, thej SON result returned bytheDataSnap REST support 
is invariably an array. This is necessary because as you can have multiple input 
parameters you can also have multiple output values, just use parameters 
passed by reference (var) or output parameters (out). 



115 The result is returned in a J SON array structure as in more complex situations you might 
have further parameters passed by reference that the server method returns along with 
its result. I 'II cover this in a second method of the current server. 
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As an example, I 've added to the server a method with a parameter passed by 

reference and very si mple code: 

fundi on TServerMet hodsl. Test Params( 

Value: string; var another: string): string; 
begi n 

Another : = another + ' * ' ; 

Result : = Value + another; 
end; 

Now if you call the server method from the browser with the URL: 

http: //I ocal host: 8 0 8 1 / F i rstSi mpl eRestServer. Fi rstSi mpl eRest Server/ 
datasnap/rest/TServer Me thodsl/TestParams / first/second 

You'll get the foil owing result, with an actual array of val ues, starting with the 
reference parameter(s) and ending with the function result: 

{ 

"result": [ 
"second*", 
" f i r s t s e c o n d * " 

] 

} 

There are further possibleand complex scenarios, of course, but thisexplains 
i n practice why thej SON result uses an array and shows that server method 
support is actually more sophisticated than it might appear at a first sight. 

Calling the REST Server from a VCL Client 

Now that we have built the server and made sure that it works, we can writea 
Delphi client application to test it. Wecan use two different approaches. One is 
to fall back to write a Delphi DataSnap client, using the specific transport layer 
provided by REST. But it won't make a lot of difference compared to using the 
HTTP or TCP transport layers of DataSnap. 

The second option, which is the one I'm going to follow, is to create a custom 
RESTclientjustlikeallofthevariousclientslbuiltinthefirstpartofthis 
chapter. This means, you could use any other language for building theclient 
application, as we are not relying on any specific Delphi support. To accomplish 
this simply create a standard Delphi VCL application, add an IdHTTP compon- 
ent to it to perform the actual REST request, an edit box for the i nput, and a 
button with the code: 
const 

strServerUrl = ' h t t p: 1 1 1 o c a I h os t : 80 8 II ' + 

'FirstSi mpl eRestServer. FirstSi mpl eRestServer/'; 
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s t r Me t h od Ur I = ' dat as nap/ r est I TSer v er Met hods 1/ Ec hoSt r i ng/ ' ; 

procedure TFormFi rstRestCI i ent. btnPI ai nCal I CI i ckfSender: TObj ect); 
va r 

strParam: string; 
begi n 

strParam := edl nput.Text; 
Show/Message ( I d HTTP 1 , Ge t ( s t r Se r v e r Ur I + 
s t r Met hodUr I + strParam)); 

end; 

This cal I bui Ids a proper U RL by concatenati ng the server address, the relative 
path to reach the given method with the REST server, and the only parameter. 
The cal I resul ts i n the fol I owi ng output: 

FirstRestClient I i=i 1h] % I' 



Hello from a Delphi Client Application 



btnPlainCall btnToJSON 





Fir-it'pvrlirirr l^^^ - " 










{"result":["Hello from a Delphi Client Application. ..ello from a 






Delphi Client Application.. .on"]} 






OK 









N ow what i s more i nteresti ng i s to extract the actual i nformati on from the 
J SON data structure returned by the server. Wecould use a manual approach, 
butl'd rather take advantage of thej SON support that is avail able in Delphi 
2010 and made avail able through theDBXJ SON unit. 

Thej SON data that our server returns is a string, but the REST server support 

creates an object with a named value (or "pair"), and places the actual value in 

an array. That's why after parsing the result of the HTTP into aj SON data 

structure, we need to navigate from the object to the pair it contains and from 

the pai r to the si ngl e el ement array i t hoi ds: 

procedure TFormFi rstRestCI i ent. btnToJ SONCI i c k ( 

Sender : TObj ect ) ; 
va r 

strParam, strHttpResult, strResult: string; 
j Value: T J S ON Va I u e ; 
j Obj : TJ SONObj ect ; 
j Pai r : TJ SONPai r; 
j Ar r a y : TJ 5 On Ar r a y ; 
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begi n 

strParam := edl nput.Text; 

strHttpResul t : = I d HTTP 1 . Ge t ( s t r Se r v e r Ur I + 

s t r Met hodUr I + strParam); 
j Va I u e : = Tj SONObj ect . Parse] SONVal ue( 

TEncodi ng. ASCI I . Get Byt es( st r Ht t pResul t ) , 0) ; 
if not As s i gned ( j V a I u e ) then 
begi n 

ShowMessage {'Error in parsing ' + strHttpResul t) ; 
Exit; 
end; 

try 

j Obj : = j V a I u e as Tj SONObj ect ; 

// get the first and only J SON pair 

j Pai r : = j Obj . Get ( 0) ; 

// pair value is an array 

j Array := j Pai r.J sonVal ue as TJ sonArray; 

// get the first and only element of array 

strResul t : = j Ar r ay. Get ( 0) . Val ue; 

ShowMessage ('The response is: ' + strResul t) ; 
finally 

j Obj . Free; 
end; 
end; 

Again, the complexity isdueto the data structure returned by the server, as in 
other circumstances it would be much easier to parse the resulting J SON and 
access to it. 



Calling the REST Server From a jQuery Client 

If all you need is to pass obj ect data from a server side Del phi application to 
another one, there could be many alternatives to using J SON. This choice 
makes a lot of sense when you want to call the Delphi compiled server from a 
J avaScript application running in the browser. This case is quite relevant 
because AJ AX (AsynchronousJ avaScript calls done in the Web browser) was 
and still is one of the driving forces behind the adoption of REST. Calling a cor- 
responding SOAP server from a Browser based program is incredibly more 
complicated. 

So, how can we create an application mi mi eking the client I just wrote but run- 
ning in the Web browser. I could have used many different approaches and 
libraries, but my preference at this time is to usejQuery, an incredibly powerful 
open sourcej avaScript library avail able at: 

http://jquery.com 
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I don't have time to delve into jQuery and its usage in this chapter, but I 'II at 
I east try to expl ai n the j Query code behi nd thi s sped f i c exampl e. F i rst of al I , the 
HTML page includes jQuery and itsj SON support: 

< h e a d > 

<ti tl e>j Query and Delphi 2010 REST</ti tl e> 
< s c r i pt s r c =" ht t p: / / j q u e r yj s . googl ec ode. com/ 
fi I es/j query- 1. 3, 2. mi n.j s" 
t y pe = " t ex t / j a va s c r i pt " ></ s c r i pt > 
<script src=" http://jquery-json.googlecode.com/ 
fi I es/j query, j son-2. 2. mi n. j s' 
t y pe = " t ex t / j a va s c r i pt " ></ s c r i pt > 
</ head > 116 

Second, the page has a very simple user interface, with some text, an input field 
and a button (without any sophisticated CSS and added graphics, as I really 
wanted to keep this focused) : 
<body> 

<hl>j Query and Delphi 2010 REST</hl> 

< p > T h i s example demonstrates basic use of jQuery calling 

a barebones Delphi 2010 REST server. </p> 
<p>l nsert the text to "Echo": <br/> 

< i n p u t t y p e = " t e x t " i d = "i nputText" si z e = " 5 0" 

value =" This is a message from jQuery"> 
<br/> 

<i n p u t type = "button" value="Echo" i d = " b u 1 1 o n E c h o " > 

<div i d = " r es ul t " >R e s ul t goes here: </div> 
</ b o d y > 

If this is the skeleton, let us now look at the actual J avaScriptcode. What we 
have to do is add an event handler to the button, read the input text, make the 
REST cal I , and fi nal ly display the result. I 'm goi ng to use the si mplest of jQuery 
selectors, based on the objects I D, to access to the page objects as i n: 

$( 11 #i nputText 11 ) 

This returns a jQuery object wrapping the input text DOM element. To define 
an event handler we can pass an anonymous method parameter to thee I i c k ( ) 
function of the button. Two more cal Is are the REST call itself (using the global 
get J SON) and theht ml ( ) call to add the result to the HTML of the element. 

This is the complete code at the heart of this demo, a very compact but not 
exactly readablej avaScript snippet: 



116 I haven't madeany attemptto optimize the HTML orj avaScript so that the examples re 
main as clear as possible. 
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$(document).ready(function() { 

$("#buttonEcho").cl ick( function! e) { 
$, get] 50N( "http://l ocal host: 8081/" 

" F i rstSi mpl eRestServer. F i rstSi mpl eRestServer/" 
"datasnap/rest/TServerMethodsl/EchoStrl n g / " + 
$( " #i nput Text " ) . val ( ) , 
function(data) { 

$ ( " # r e s u I t " ) . h t ml (data, r e s u I t . j o i n ( 1 1 ) ) ; 

} ); 

}); 

}); 

J ust by openi ng an HTM L fi le with the given code you can cal I the custom 
server, but only if the browser permission settings allow an AJ AX call froma 
local fileto a local REST server. I n general, most browsers will only let you call 
REST servers on the same site originating the HTML page. 

I n any case, I nternet Explorer seems to work fi ne on this local fi le, after 
enabling local scripts and asking for limited security (availablesi nee the file is 
on the local machine, seethe icons in the status bar): 



I jQuery and Delphi 2010 REST - Windows Internet Explorer Ifl 



oo 


C:\code\dh2Q10codeW ~ 


*f 


X | 


£1 Google P - 


Favorites 


ig jQuery and Delphi 2010 ... 




IS ' 0 ' E3 # ' Page- Safety- 



jQuery and Delphi 2010 REST 

This example demonstrates basic use of jQuery calling a barebone Delphi 2010 REST server. 

Insert the text to "Echo": 
This is a message from jQuery 
I Echo I 



This is a message from jQuery.. .his is a message from jQuery.. .ry 



Done j$> |k Computer | Protected Mode: Off -*fl - ^100% - 



On other web browsers, you need to let the server return both the HTM L page 

and the REST data, which is not a terribly big deal as our REST server is indeed 

a web server. So, al 1 1 had to do for a "server side" sol ution (as far as the web 

browser is concerned) is to add an action to the web server module (which I 

hooked to the "/ f i I e" U R L ) and retu r n the H T M L f i I e f rom i t : 

I procedure TWe b Mo d u I e 2 . We b Mo d u I e 2 We b A c t i onl temlActi on( 
Sender: TObject; Request: TWebRequest; 
Response: TWebResponse; var Handled: Boolean); 
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var 

strRead: TStreamReader; 
begi n 

strRead : = TStreamReader.Create('/'n'esfC7/e/?r./?fm/'); 
try 

Res po ns e . Co n t e n t := strRead. ReadToEnd; 
finally 

st r Read. Free; 
end; 
end; 

N ow we can refer to gi ven server page wi th the / f i I e U R L , get the f i I e wi th the 
J avaScript code, and let it call our REST server: 

' — — — — ? ;„n S lr | a | B | M £3»r 
J D jQuery and Delphi 2010 R,„ .■ ^jE^ 

■» C * http://localhost:80Sl/FirstSimpleRestServer.FirstSimpleRestServer/file ► □ - A " 

jQuery and Delphi 2010 REST 

This example demonstrates basic use of jQuery calling a barebone Delphi 2010 REST server. 
Insert the text to "Echo": 

["This is a message from jQuery | 
| Echo 1 

This is a message from jQuery.. .his is a message from jQuery.. .ry 

Si 

The difference between this and the previous image is not just that I 'm using a 
different browser, but that I'm pointing to a different URL. Rather than loading 
a file, in this second case I'm usi ng the server side REST application as a full 
Web server, return i ng the HTM L used for cal I i ng the same server vi a AJ AX . 



Returning and Updating Objects 
with REST HTTP Methods 

Now that we have explored the development of a very si mple REST server with 
Delphi 2010 DataSnap support, it isti me to try to figure out the actual code we 
can write on the server to make it more powerful . As we have seen, the server 
returns J SON data, converting the result of your functions to this format. We 
can pass an object as result and have its data converted. However, in most 
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practical situations, it would be better to take full control and create specific 
J SON objects on the server side and return them. That is going to be one of the 
goals of our next project. 

The same project will also show how to process other HTTP methods beside the 
Get method, letting us not only retrieve but also modify a server side object 
from a simple Browser- based client written in J avaScript. Finally, in doing this 
we'll focus on URL management and figure out how to makethem nicer and 
more flexible. 

Returning J SON Objects and Values 

For this second project I 've used the DataSnap WebBroker Wizard, picked the 
Web App Debugger architecture (again), and decided to use aT P e r s i stent 
base class, as I don't need a data module as target class for the REST calls. As 
you need specific RTTI support, the rule is to inherit (at least) from 
TPer s i stent and mark the class with the$ METHODI NFO directive, as in the 
following generated code: 

{ $METH0DI NFO ON} 
type 

TObj ectsRest = c I a s s ( T Pe r s i s t e nt ) 
public 

function PI a i n D a t a (name: string): TJSONValue; 
function DataMarshal (name: string): TJSONObject; 
end; 

{ $METH0DI NFO OFF} 

As you can seel've added acoupleof functions to the class for returning either 
a val ue or a ful I object 117 . Later I 'I I add other methods to the class. 

The data structure behind this application is a list of objects of a custom type 
(which could have been written in a more object-oriented way, but I wanted to 
keep it si mple for the sake of the example) : 
type 

T My Da t a = class ( T Pe r s i s t e n t ) 
public 

N a me : String; 

Value: Integer; 
publ i c 

constructor Create (const aName: string); 
end; 



117 M ore correctly, al I the data values of a ful I object. 
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The objects are kept in adictionary, implemented using the generic container 
class T Ob j ectDi cti onary<TKey,TVal ue> defined in theGenerics.Collections 
unit since Delphi 2009. This global object is initialized when the program starts 
with the addition of a couple of predefined objects. Notice thatl useaspecific 
AddToDi cti onary procedure to add theobjects, to make sure theobject name 
is in sync with thedictionary key and it has a random value if none is provided: 
va r 

DataDict: TObj ectDi cti onary <s t r i n g , T My Da t a >; 

procedure AddToDi cti onary (const aName: string; 

nVal: Integer =-1); 
va r 

md: T My Data; 
begi n 

md := T My Da t a . Cr e a t e (aName); 
if nVal <> - 1 t hen 
md , Va I u e : = n Va I ; 
Da t a D i c t . Ad d ( aName, md) ; 
end; 

initialization 

DataDict := TObj ect Di ct i onar y <stri ng, TMyData>. Create; 
AddToDi cti o n a r y ( ' Sa mpl e') ; 

H avi ng thi s data structure i n pi ace, we can now focus on the f i rst two sampl e 

methods used to return the J SON values. The first returns the value of the 

given object (picking a default one if no parameter is passed to the fundi on): 

function TObj ec t s Res t . P I a i n Da t a ( na me : string): TJSONValue; 
begi n 

if Name = 11 then 

name := 'Sample'; II default 

Result := TJ S ONNu mbe r . Cr e a t e ( Da t a Di c t [ na me ] . Va I u e ) ; 
end; 

If we use an URL with or without the parameter (as in the following two lines): 

/ datasnap/ rest/TObj ectsRest/PI ai nDat a/ Test 
|/datasnap/rest/TObj ectsRest/PI ai nData 

we will still get a J SON response, either for the specific object or a default one: 

{"resul t": [ 8 9 7 8 ] } 

What if we want to return a complete object rather than a specific value? Our 
REST server cannot return a T 0 b j ect val ue, as the system has no way to con- 
vert it automatically, but it can indeed usethenewj SON marshaling support 
for converti ng an existi ng object to thej SON format: 

function TObj ec t s Res t . Da t a Ma r s ha I ( na me : string): TJSONObject; 
va r 

j Marshal : Tj SONMarshal ; 
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begi n 

j Marshal := TJ SOMMarshal . Create(TJ SONConverter. Create); 
Result : = j Marshal . Marshal ( DataDi ct[ name] ) 
as Tj SONObj ect ; 

end; 

This approach is mostly useful when you need to recreate the object in the 
Delphi client application, while it is not particularly handy i n the case where 
the client is written in another language. TheresultingJ SON looks a little ugly: 

{ 

11 r e s u I t 11 : [ { 

"type": " Ob j e c t s Res t S e r ve r _ CI asses. TMyData" , 
11 i d 11 : 1 , 
"fields": { 

■ Name" : "Test", 

" V a I ue" : 8 0 6 8 } 

}] 

} 

So, what would be the best option to return aj SON object? I think it would be 

to create one on the server side, using the support classes. This is what I 've 

done in the My Da t a function: 

function TObj ec t s Res t . My Da t a ( na me : string): TJSONObject; 
va r 

md: TMyData; 
begi n 

md : = Da t a Di c t [ na me ] ; 

Resul t : = Tj SONObj ect . Create; 

Res ul t , AddPai r ( TJ SONPai r . Cr eat e ('Name', md.Name)); 
Resul t. AddPai r ( TJ SONPai r. Create ( 

' Val ue' , TJ SON Number. Createf md. Val ue) ) ) ; 

end; 

As you can see I 've created a TJ SONObj ect and added two pai rs (or properties) 
for the name and the value. I could have used adynamic name (that is, used the 
name for the name part of the pair), but thiswould have made it harder to 
retrieve the data on the cl ient side. The result of this code should look I i ke the 
foil owing cleaner J SON code: 
{ 

11 r e s u I t " : [ { 
" Name" : "Test" , 
11 Val ue" : 8 0 6 8 

}] 

} 
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Listing Objects with a TJ SONArray 

N ow havi ng a I i st of obj ects, you mi ght wel I need to access the I i st of obj ects. 
Having a list with the names only (and no data) will be useful when buildinga 
cl i ent si de user i nterf ace. 

For returning a list you can useaTJ SONArray, which in this case will bean 

array of stri ngs I create usi ng an enumerator on the Keys of the dictionary: 

function TObj ectsRest . Li st : TJ SONArray; 
va r 

s t r : string; 
begi n 

Re s u I t : = TJ SONArray. Create; 
for st r in Dat a D i ct . Keys do 
begi n 

Resul t . Ad d ( st r ) ; 
end; 
end; 

The result of this call is an array in J SON format, which in turned is passed (as 
usual) in an array called result (hence the double nested array notation): 

{ 

"result":! 

[ "Test" , 11 Samp I e"] 

] 

} 

Now that we have a way to return alist of values and fetch the data of each indi- 
vidual element, we can start building a user interface. 

Sending the List to the jQuery Web Client at 
Start-up 

Rather than having to build the initial HTML with the list of values, to let the 
user pick one, we can fully exploit the AJ AX model . 

The page on startup will have no data at all, only the HTML elements and the 
J avaScri pt code. As soon as the page is loaded, even without user i ntervention, 
it wi 1 1 ask the server for the actual data and popul ate the user i nterf ace. 

As an example, on start up the program shows the val ue of the Sample object, 
using the foil owing HTML elements and AJ AX call (executed when document 
is ready, that is the DOM has finished loading): 

| <d i v >S a mp I e : <s p a n i d = " s a mp I e " ></ s pa n ></ d i v > 
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<s c r i pt > 

va r bas eUr I = 

"/Obj ectsRestServer. RestObj ects/dataSnap" + 
"/rest/TObj ectsRest/"; 

$(document).ready(function() { 

$. get J S0N( baseUr I + " My Da t a / S a mp I e" , 
function(data) { 

st r Resul t = data. result[0]. Value; 
$( " #sampl e" ) . ht ml ( st r Resul t ) ; 

} ); 
</ s c r i pt > 

The AJ AX call to My Da t a passes the object name as a further URL parameter 
and extracts from the result array the property/ pair called Value, showing it in 
an empty span HTM L element. Something similar (but somewhat more com- 
plex) happens for thelist. Again, thereisan AJ AX call, but this time we have to 
build the resulting HTML. The operation isperformed in aseparate 
r e f r e s h L i s t function called both automatically at start-up and manually by 
the user: 

<div>Current entries list: 

<a href =" #" i d = " r ef r es h " >Ref r es h </ a > 
<s pa n i d = " I i s t " ></ s pa n></ d i v > 

function refreshLi st( ) 
{ 

$. getj 50N( baseUrl + "list", 
f u nc t i on ( da t a ) { 

var thearray = da t a . r es ul t [ 0 ] ; 
v a r rati ngMarkup = [ " <b r >" ] ; 
for (var i =0; i < t he a r r a y . I e n g t h ; i ++) { 
rating Ma r k u p = rati ngMarkup + 
" <a href ='#'>" + thearray[i] + "</a><br>"; 

} 

$("#1 i st"). html (rati ngMarkup); 

} ); 

}; 

The code uses a for loop to scan the resulti ng array. I could have used the 
$. each enumeration mechanism of j Query, but this would have made the code 
more complex to read. The for loop creates the HTML, which is later displayed 
in the span place-holder with the given ID. In the next page you can seethe 
sample output with the val ue of the Sample object (the code shown earl ier) pi us 
the list of the values returned in thej SON array. 

Asl mentioned earlier, ther ef reshLi st function is called at start-up (in the 
ready event handler) and also connected with a corresponding link, so that the 
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j D jQuery and Delphi 2010 R... -■ \yj>\ 

*■ - C ^ http://localhost:3081/ObjectsRestServer.RestObjects ► □"A" 

jQuery and Delphi 2010 REST 

This example demonstrates the use of jQuery for reading and modifying objects in a Est. 
Sample: 4635 

Current entries list: Refresh 
Test 
Sample 

user can later refresh the data of the list without having to refresh the entire 

HTML page: 

$(document).ready(function() { 
refreshLi st( ) ; 

$("#refresh").cl i ck(functi on(e) { 

refreshLlstf); 
} ); 

There is actually a little more to the code generation. As soon as we have the 

HTM L for the list, which is a list of I i nks, we need to hook code to those links so 

that sel ecti ng each entry of the I i st the cl i ent appl i cati on wi 1 1 1 oad the corres- 

pondi ng server si de obj ect. The user i nterface for the obj ect data i s made of two 

input boxes, which will later use also for manipulating the object data. The 

behavior is added to each anchor within the list container. 

$( " #1 i st " ) . f i nd( " a" ) . cl i c k( f unct i on( e) { 
var wasclicked = $ ( t hi s ) ; 

$. getj S0N( baseUrl + " My Da t a / " + $ ( t hi s ) . ht ml ( ) , 
function(data) { 

strResul t = data. result[0]. Value; 

$ ( " #i n p ut Na me " ) . v a I ( wa s c I I eked, h t ml ( ) ) ; 

$("#i nputVal ue"). val (strResul t); 
} ); 

}) ; 

Notice the use of the$ ( t h i s) call, which is moreorlesstheSender parameter 
foraDelphi event. Its text is the html content of the element that wasclicked, 
which is the name of the element we have to pass to the server i n the URL, with 
the expression: 

baseUrl + " My Data / " + $( t hi s ) . ht ml ( ) 
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N ow wi th thi s code i n pi ace we can see the effect of cl i cki ng on one of the el e- 
ments of the I ist: A further AJ AX cal I wi 1 1 reach our server aski ng for a given 
val ue, and the returned val ue is displayed i n two i nput text boxes: 





/ Q jQuery and Delphi 2010 R... x 


<- C "& http://localhost:8081/ObjectsRestServer,RestObjects# ► A 




jQuery and Delphi 2010 REST 




This example demonstrates the use of jQuery for reading and modifying objects in a Est. 




Sample: 4635 




Current entries list: Refresh 




Test 




Sample 




Current Element: 




(Test 




5138 




Update Delete New 




Log info goes here: 





As you can see above, the program let us retrieve a val ue, but has also three 
buttons to perform the most common operations (the so cal led CRU D i nterface 
- Create, Read, Update, Delete). This issupported in HTML usi ng the 4 code 
HTML methods, respectively PUT, GET, POST, and DELETE. How these are 
supported by a Delphi 2010 REST server is the subject of the next section. 

HTTP Methods: POST, PUT, and DELETE 

U p to now we have seen only how to get data from our REST server, but what 
about updating it? The generally agreed idea in REST is to avoid using specific 
URLs for identifying the operations, but use an URL only to identify server side 
objects (like My D a t a / S a mp I e in our case) and use the HTTP methods to indic- 
ate what do to. 

Now if Delphi's REST support simply mapped URLs to methods, we would 
have been out of luck, I nstead, it maps URLs pi us the HTTP method to meth- 
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ods, using a rather simple scheme: the name of the operation isprepended to 
the method name, using the foil owing mapping: 

GET get (default, can be omitted) 

POST update 
PUT accept 

DELETE cancel 

You can customize these mappings by dealing with the four corresponding 
event handlers of the DSHTTPWebDispatcher component. I f we decide to go 
with the standard naming rules, to support the various operations we need to 
def i ne our server cl ass as: 
type 

TObj ectsRest = class(TPersistent) 
public 

function List: TJ SONAr ray; 
function My Da t a (name: string): TJSONObject; 
procedure update My Data (name, value: string); 
procedure cancel My Data (name: string); 
procedure accept My Data (name, value: string); 
end; 

Togetor delete an element we only need the name, while to create or update it 
we need a second parameter with the data. 

The implementation of the three new methods is rather simple and direct, also 

because they don't need to return a value (needless to say I should have 

checked that parameters are not empty and that the server si de obj ect real I y 

exi sts i n the contai ner ) : 

procedure TObj ectsRest. updateMyData (name, value: string); 
begi n 

Dat a D i ct [ name] . Val ue := StrTolntDef (Value, 0); 
end; 

procedure TObj ectsRest. cancel MyData(name: string); 
begi n 

DataDi ct. Remove( name) ; 
end; 

procedure TObj ec t s Res t . ac c e pt My Da t a ( na me, value: string); 
begi n 

AddToDi ct i onary (name, StrTolntDef (Value, 0)); 
end; 
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Editing Data with jQuery 

N ow that we have the CRUD operations avail able on the REST server, we can 
compl ete our J avaScri pt client appli cati on wi th the code of the th ree ed i ti ng 
buttons (the i mage of the browser- based user i nterf ace was shown earl i er) . 

While jQuery has specific support for the get operation (with different versions, 
including the J SON -specific one we have used earlier) and some support for 
post operations, for the other HTTP methods you have to use the lower level 
(and slightly more complex) $ . aj ax call. Thiscall has as a parameter a list of 
paired values, up to a dozen that are possible. The more relevant parameters 
are the type and theURL, whiledata lets you pass further POST parameters. 

Posting our update is rather simple, and we can providethedatatoour REST 
server usi ng the URL: 

$("#buttonUpdate"). cl i ck(functi on(e) { 
$ ■ a j a x ( { 

type: "POST", 

u r I : baseUr I + " My Da t a / " + 
$(" #i n put Name" ). val ( ) + "/ " + 
$( " #i nputVal ue") . val ( ) , 
success: function! ms g ) { 

$( " #1 og" ) . ht ml ( msg) ; 

} 

}) ; 

}); 

Deleting is equally simple, as we need to create the URL with the reference to 

the object we want to remove: 

$( " #but t on Del et e" ) . cl i ck( f unct i on( e) { 
$ . a j a x ( { 

type: "DELETE", 
ur I : baseUr I + " My Da t a/ " + 
$ ( " #i n p u t Na me " ) . v a I ( ) , 
success: function! msg){ 

$( " #1 og" ) . ht ml ( msg) ; 

} 

}); 

}); 

1 1 took me some more ti me to figure out how to i implement PUT, as if you don't 
provide any data, some browsers (notably Chrome) will post the data as 
"undefined" andthiswill maketheHTTP input parsing of the REST server 
crash with an error. 
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As we need to pass i nformation (and we cannot pass more parameters than the 

server requires, which will be equally flagged as an error), what we can do is 

replace one of the URL elements with a corresponding data element: 

$( " #bu 1 1 on Ne w" ) . c I i c k ( f unc t i on ( e ) { 
$ . a j a x ( { 

type: 1 PUT 1 , 

data: nputVal ue") - val ( ) , 

u r I : baseUr I + " My Da t a/ " + 
$("#i nputName") - val ( ), 

success: f u n c t i o n ( ms g ) { $ ( " # I o g " ) . h t ml ( ms g ) ; } 

}); 

}) ; 

Notice that j Query documentation specifically warns against using PUT in 
browsers, as you might get mixed results. That might as well be the reason for 
which a number of REST services (including those from M icrosoft) tend to use 
POST for both updating and creating server side objects. I prefer keeping the 
two concepts separate, for clarity and consistency, whenever possible. 

With the three extra methods added to our class and the proper AJ AX calls, we 
now have an example with a complete Browser-based user interface for creat- 
ing and editing objects in our REST server. Here I 've created a few objects: 



Coogr.- | Q |@ \m£2^> 


/ D jQuery and Delphi 2010 R... 


*■ G il http://localhost:8081/ObjectsRestServer.RestObjects# ► ; Q- A- 


jQuery and Delphi 2010 REST 




This example demonstrates the use of jQuery for reading and modifying 


objects in a list. 


Sample: 4635 




Current entries list: Refresh 




One 




Three 




Sample 




Two 




Current Element: 




(Two 




1000 




| Update | | Delete | | New | 
{"result":[]} 
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Building a Database Oriented REST 
Server 

If the original idea behind DataSnap focused on moving data tables from a 
middle-tier server to a client application, it might be quite odd at first to realize 
that you cannot return a dataset from a REST server written in Delphi 2010. 
Well, you cannot return it directly or as easily as you return its XML represent- 
ation, but you can create a J SON result with all of the data of a Delphi dataset. 
That's the focus my I ast example. 

The program is quite bare bones, as all it does is return the data of a complete 
Dataset, with no metadata. It could be extended in several ways and lacks a pol- 
ished user i nterface, but should get you started. The server class has only one 
method, returning an enti re dataset in a J SON array: 

function TSer ver Dat a. Dat a : TJ SONArray; 
va r 

j Record: TJ SONObj ect ; 
I : Integer; 
begi n 

CI i ent Dat aSet 1. Open; 

Result : = TJ Son Array. Create; 

whi I e not CI I ent DataSet 1. EOF do 
begi n 

j Record : = TJ SONObj ect . Create; 
for I := 0 to CI i ent Da t aSet 1. F i el dCount - 1 do 
j Record, AddPai r ( 

CI i ent Dat aSet 1 . F i e I d s [ I ] . F i e I d Na me , 

TJ SON St r i ng. Cr eat e ( CI i e n t Da t a Se 1 1 . F i e I d s [ I ] . As St r i ng ) ) ; 
Res ul t. AddEI ement(j Record) ; 
CI i ent Dat aSet 1. Next ; 
end; 
end; 

This method is invoked by the client application after loading the page, build- 
ing an HTML table dynamically, with thefollowingjQuery code (you should 
have become fami I i ar with the codi ng style by now) : 

$(document).ready(function() { 

$. get J S ON ( " / Dat a Res t Ser ver . Res t Dat aSer ver / da t as nap" + 
" / r es t / TSer ve r Da t a / Da t a " , 
function(data) { 

var t hear ray = dat a. resul t [ 0] ; 
var rati n g Ma r k u p = " <t a b I e bor der =' 1' >" ; 
for (var i =0; i < t h e a r r a y . I e ng t h ; i ++) { 
rati n g Ma r k u p = rati ngMarkup + "<trxtd>" + 
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}) 



} ) 



thearray[ i ] . Company + "</tdxtd>" 
t he a r r a y [ i ] . Ci t y + "</tdxtd>" + 
t hear r ay[ i ] . St a t e + " </ 1 dxt d>" + 
thearray[ i ] . Country + "</tdx/tr>" 

} 

rating Markup = rating Markup + "</ table >" 
$ ( " #r e s u I t " ) . ht ml (rati ngMar kup) ; 



The bare- bones result is visible below in a web browser: 



/ Q jQuery and Delphi 2010 R... 

<- O & http://localhost:80Sl/DataRestServer.RestDataServer 



Coqgic \j 



jQueiy and Delphi 2010 REST 



This is your data 



Kauai Dive Shoppe 


Kapaa Kauai 


HI 


US 


Unisco 


Freeport 




Bahamas 


Sight Diver 


Kato Paphos 




Cyprus 


Cabman Divers World Unlimited 


Grand Cayman 




British West Indies 


Tom Sawyer Diving Centre 


Christiansted 


St. Croix 


US Virgin Islands 


Bhie Jack Aqua Center 


Waipahu 


HI 


US 


VIP Divers Club 


Christiansted 


St. Croix 


US Virgin Islands 


Ocean Paradise 


Kailua-Kona 


HI 


US 


Fantasu'que Aquatica 


Bogota 




Columbia 


Marmot Divers Club 


Kitchener 


Ontario 


Canada 



Can weimproveit a little bit? The final version of the program adds some 
metadata support to improve the final output. 

On the server side, there is a second function returning an array of field names 

from the dataset field definitions: 

function TSer ver Dat a. Met a : TJ SONArray; 
va r 

j Record: TJ SONObj ect ; 
I : Integer; 
begi n 

CI i ent Dat aSet 1. Open; 

Result : = TJ Son Array. Create; 

for I := 0 to CI i ent Dat aSet 1. F i el dDef s . Count - 1 do 
Res ul t . Ad d ( CI i ent Dat a Set 1. Fi el dDef s[ I ] . Name) ; 

end; 
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The client- side J avaScript has been expanded with asecond call totheREST 

server to get the metadata: 

$. get J S ON ( " / Dat a Res t Ser ver . Res t Dat aSer ver / da t as nap/ " + 
" r es t / TSer ver Da t a/ Met a " , 
function(data) { 

the Me t a Array = data.result[0]; 

This information is used to create the table header and to access the object 
properties dynamically, with the notation: 

obj ect[ "propertyname"] 

I n our case the existing code used to access to an object with the property sym- 
bol: 

| t hearray[ i ] . Company 

becomes the foil owing code that reads the property by name, usi ng the name of 
the field stored in the metadata: 

I I h e a r r a y [ i ] [ t he Me t a Ar r a y [ j ] ] . 

This isthecompletej avaScript code used to create the HTM |_ markup™ 3 : 

var rati ngMarkup = " <t a b I e bor der =' 1' ><t r >" ; 

// header 

for (var j =0; j < t he Me t a Ar r a y . I e ng t h; j ++) { 
rati n g Ma r k u p = rati ngMarkup + "<th>" + 
t heMet a Ar r ay[ j ] + " </ 1 h>" ; 

}; 

rati ngMarkup = rati ngMarkup + " </ t r >" ; 
// content 

for (var i =0; i < t hear ray. I engt h; i ++) { 
rati n g Ma r k u p = rati ngMarkup + " <t r >" ; 
for (var j =0; j < t he Me t a Ar r a y . I e ng t h ; j ++) { 
rati ngMarkup = rati ngMarkup + "<td>" + 
t hear r ay[ i ] [ t heMet a Ar r a y [ j ] ] + " </ 1 d>" ; 

}; 

rati ngMarkup = rati ngMarkup + "</tr>"; 

} 

rati ngMarkup = rati ngMarkup + " < / 1 a b I e > " ; 
The output of this extended version becomes slightly nicer (and more flexible): 



IIS For concatenating script inj avaScript it is more common, and shorter, to use the += op- 
erator, but here I 've kept the code more "Pascal- 1 ike", to make it easier for the average 
reader of this book. 
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/ Q jQuery and Delphi 2010 R... 

*" - G H http://localhost:8081/DataRestServer.RestDataServer ► □ - A" 

jQuery and Delphi 2010 REST 



This is your data 



Cust>o 


Company 


Addrl 


Addrl 


City 


State 


Zip 


CouDtty 


Pboue 


1221 


Kauai Dive 
Shoppe 


4-976 

Sugarloaf 

jrivvy 


Suite 
103 


Kapaa Kauai 


HI 


94766- 
1234 


US 


808- 
555- 


1231 


Unisco 


PO Box Z- 
547 




Freeport 






Baliamas 


809- 
555- 
3915 


1351 


Sight Diver 


1 Neptune 
Lane 




Kato Paphos 






Cyprus 


357-6- 
876708 


1354 


Cayman 
Divers 
World 
Unlimited 


PO Box 
541 




Grand 
Cabman 






British 

West 

Indies 


011-5- 
697044 


1356 


Tom 
S awyer 
Diving 
Centre 


632-1 
Third 
Frydenhoj 




Christiansted 


St. Croix 


00820 


US Virgin 
Islands 


504- 
798- 
3022 


13S0 


Bhie Jack 

Aqua 

Center 


23-738 

Paddington 

Lane 


Suite 
310 


Waipahu 


HI 


99776 


US 


401- 
609- 
7623 



4 | itr ► 



Again, this serves only as a starting point, and I didn't use any of the jQuery 
plug- ins, which would add significant capabilities to HTML tables, turning 
them into powerful user interface grids, with sorting, filtering, and editing cap- 
abilities. 



REST Server Alternatives 

After an introduction on building a REST server with the plain WebBroker 
architecture, in this chapter I've delved into the development of REST applica- 
tions in Delphi 2010 using the specific DataSnap support. With thissupport, as 
we have seen, you can map server methods to U RLs and handle the various 
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HTTP methods. I have also introduced the development of simplej avaScript 
cl i ents usi ng the j Query I i brary. 

Now the question becomes, is this the suggested way to implement a REST 
server in Delphi? I think the current DataSnap REST mapping has a few limita- 
tion, includingaveryrigidfirstpartoftheURL (a thing that can be worked 
around), the i nabi I ity to combi ne HTTP query parameters with U RL elements 
(the URL should refer to a resource in REST, but any additional parameter 
should be passes as an HTTP parameter), and the availability of onlyone return 
type, J SON (which is quite handy, but still having alternatives would be better). 

On the positive side, this architecture integrates very well with DataSnap and 
server side methods (making it well suited to provide a back-end to both Delphi 
clients and browser-based applications with a single server side technology), it 
is quite simple to use (and you don't have to work with any low-level techno- 
logy, do your own URL parsing, and soon), and let's you stay focused on Delphi 
code for your servers. 

I do have a lot of investment in server side web and REST applications written 
i n Del phi , and i n the recent years I 've started pi ayi ng with and i ntroduci ng at 
conferences a Delphi Web Application REST Framework™ (that is, DWARF), 
which at thisti me is stillnot publicly avai I abl e. . . si mpl y because i t i s too 
sketchy and unfinished to be published. I've seen other ongoing efforts to clone 
Rails in Delphi and offer other REST server architectures. 

I think that if you want to build a very large REST application architecture you 
should rol I out your own technology or use one of these prototypical architec- 
tures. For a small to medium size effort, on the other hand, you can probably 
benefit from the native DataSnap support. This is particularly true if you want 
the REST access to go along with a native DataSnap HTTP access focused on 
Delphi clients. Inthiscase, in fact, you get the REST support for free as you 
built your multi-tier Delphi architecture. 



119 I mentioned my framework only once in my blog, but without providing much detail, as 
you can see at http://blog.marcocantu.com/blog/web_dev_stacks_delphi.html 
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What's Next 

As thi s i s the end of the book there i s no i ntroducti on to the f ol I owi ng chapters, 

but only a reminder of where to find extended information. As mentioned in 

the i ntroducti on, refer to the book web page, my home page or my blog: 

h 1 1 p : / / www. marcocantu. com/dh2010 
h 1 1 p : / / www. marcocantu. com 
| http: / /blog. ma rcocantu.com 

It is very likely you'll find corrections and updates to the book, and possibly 
additional chapters in PDF format which you could buy online. 

I hope you have enjoyed the book and it will helpyou use the extended power 
of Delphi 2010 in a more effective way. If this isthecase(but also if you found 
errors, omissions, or just disliked the book) an email or online message of any 
form is always welcome. 

On to the next Delphi! 
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